drei splits into a web entry and a native entry, and native drops two components
🥉 useful helpers for react-three-fiber
At a glance
- What is it?
- @react-three/drei is a component shelf for react-three-fiber: cameras, controls, loaders, shaders, and gizmos you would otherwise write yourself. The install is one npm line, and the interesting part is where the two entry points diverge.
- Who is it for?
- Take drei when you are building a react-three-fiber scene and want working controls, loaders, and gizmo components instead of your own wrappers, and stay on the v10 line unless you have read the v11 alpha notes. Skip it if your scene needs one loader from three and nothing else, because three already ships those under three/examples/jsm and drei adds a dependency tree on top.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 25 days ago.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- pmndrs/drei10,163 ★ · +280
| Repository | 2026-09-22 | 2026-11-15 |
|---|---|---|
| pmndrs/drei | 9.9k | 10.2k |
280 Stars in the last 54 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
One npm line, then a named import of components
Installation is a single package, and use is a single import.
npm install @react-three/dreiimport { PerspectiveCamera, PositionalAudio, ... } from '@react-three/drei'The package declares `"main": "index.cjs.js"`, `"module": "index.js"`, and `"types": "index.d.ts"`, so a bundler picks the ES module and TypeScript finds the declarations without extra wiring. The `package.json` also sets `"sideEffects": false`, which lets a bundler drop unused drei imports instead of pulling the whole shelf into your chunk.
That last detail matters for a large scene. drei is a collection, not a module, and the components are unrelated to each other: a `Grid` and a `Gltf` share no state. The cost of the collection is the number of exports, and tree shaking is what keeps that cost from being paid in full.
The native entry point is not a subset of the web one
`package.json` maps the React Native field to a different file: `"react-native": "native/index.cjs.js"`, against `"main": "index.cjs.js"` for web. The import changes with the target.
import { PerspectiveCamera, PositionalAudio, ... } from '@react-three/drei/native'The gap is not subtle. The `native` route does not export `Html` or `Loader`; the default export does. `Html` is the component that projects DOM into the scene, so on native you have no in-scene DOM. `Loader` is the Suspense-friendly wrapper used while assets load, so on native you wire your own suspense boundary.
If a codebase shares components between web and native, that difference is a build-time break rather than a runtime one. Any file importing `Html` from `@react-three/drei` will resolve fine on web and fail to resolve on native, and the fix is a per-platform import path rather than a feature check.
three-stdlib replaces three/examples/jsm, so check where your loaders come from
drei carries an important note about its addon source: this package uses the stand-alone `three-stdlib` instead of `three/examples/jsm`. The components that wrap loaders and controls resolve their underlying classes from that separate package.
For a reader this has one practical consequence. If your own code imports a class from `three/examples/jsm` and passes it to a drei component that expects the `three-stdlib` copy, the two are different objects even when they look identical. The path you import from has to stay consistent across your code and drei's internals.
There is a second, smaller consequence for bundle size and for upgrades. The three.js addons you would otherwise take from the three package itself are now reachable through a dependency drei pulls in, so a project can end up with loaders and controls arriving from two different places. If you only need `GLTFLoader` or an orbit control and nothing from drei, take it straight from `three/examples/jsm` and skip the dependency entirely. drei earns its weight when you want the React component, not the underlying class.
The version in the repository is 0.0.0-semantic-release, not the one on npm
`package.json` in the repository root is private and its version field is `"0.0.0-semantic-release"`. The published version is stamped by the release tooling, not by hand, so reading the repo tells you nothing about what you installed.
The `copy` script shows what actually reaches npm: it copies `package.json`, `README.md`, and `LICENSE` into `dist`, then rewrites that JSON to set `private` to false and delete `devDependencies`, `optionalDependencies`, and `scripts`. What you read on the registry is a transformed copy, not the file in git.
The consequence for adoption is that the repo file will never answer a version question. Read the npm tag instead. The current tags show a v10 line and a v11 line moving at once: v10.7.9 dated 2026-09-25, v11.0.0-alpha.7 dated 2026-09-05, and v11.0.0-alpha.6 dated 2026-08-31. The last push to the repository was on 2026-10-21. So an install that follows the newest tag and an install that follows the latest stable can land on different major versions of the same library, and the alpha line is publishing faster than the stable one in this window.
The README keeps an anchor table it tells you not to update
The anchor list in the README is frozen on purpose. The warning above it says the table is an archive of anchor links with their new locations on the documentation site, and that the links are for reference only and must not be updated.
That instruction has a cost for anyone arriving from search or an old tutorial. The anchors still look like the current API, so a link ending in `#softshadows`, `#marchingcubes`, or `#gltf--usegltf` resolves to an archived position rather than the live page. The current documentation is at `https://pmndrs.github.io/drei`, and the README links `https://drei.pmnd.rs/` for the landing page. If a component's props changed after that table was frozen, the old anchor will not tell you.
The table is still worth reading as a map of scope, because it names the whole surface in one screen: cameras such as `PerspectiveCamera` and `CubeCamera`; controls such as `CameraControls`, `ScrollControls`, `PointerLockControls`, and `KeyboardControls`; gizmos such as `PivotControls`, `TransformControls`, and `Grid`; abstractions such as `Text`, `Svg`, `MarchingCubes`, `Splat`, and `Sampler`; shaders such as `MeshTransmissionMaterial` and `shaderMaterial`; and loaders such as `useGLTF` and `useFBX`.
Tests need a browser, a typecheck, and a Chromatic token
The `test` script is a chain of four gates rather than a single runner.
"test": "yarn eslint:ci && yarn typecheck && yarn prettier && (cd test/e2e; ./e2e.sh 0.180)"Style and formatting failures block the run before any rendering happens, and the typecheck runs with `"--strict"`. The end-to-end part is a shell script in `test/e2e` that takes a version argument, so browser coverage is tied to an explicit three.js version rather than to whatever your lockfile resolves. The build mirrors that split: `rimraf dist`, then type declarations, then rollup, then two copy steps, one for web and one for native.
Visual changes are checked through Storybook and Chromatic. The repo has `.storybook/`, a `storybook` script that serves on port 6006, and a `chromatic` script that runs `chromatic --project-token $CHROMATIC_PROJECT_TOKEN`. Only the storybook and build-storybook scripts pass `--openssl-legacy-provider` through `NODE_OPTIONS`.
Where drei is the wrong dependency
drei is a shelf of React components, and a shelf you do not need is weight. Three cases where it is the wrong call.
First, when you need one addon and nothing else. three ships loaders, controls, and math helpers under `three/examples/jsm` already. Adding drei for a single `useGLTF` brings in a package whose own note says it routes through `three-stdlib`, and you end up with two addon sources in one app.
Second, when your target is React Native and the component you actually want is `Html` or `Loader`. Both are absent from the native route, so the parts of drei you would use for a DOM overlay or an asset preloader simply are not there. Read the component list for the native target before designing around it.
Third, when you need behaviour drei does not wrap. The library is a collection of components for a declarative scene graph; a custom shader pipeline, a custom raycast scheme, or a bespoke load path is work you write yourself, and drei only supplies the pieces around it, such as `shaderMaterial`, `useContextBridge`, and the `Sampler` and `Trail` helpers. The README invites components back into the project, which tells you the intended boundary: shared React wrappers in, engine-level machinery out.
Editorial conclusion
Take drei when you are building a react-three-fiber scene and want working controls, loaders, and gizmo components instead of your own wrappers, and stay on the v10 line unless you have read the v11 alpha notes. Skip it if your scene needs one loader from three and nothing else, because three already ships those under three/examples/jsm and drei adds a dependency tree on top. Before upgrading, check which of your imports come from @react-three/drei rather than @react-three/drei/native, since Html and Loader only exist on the default export.
Frequently asked questions
What is React Drei?
It is a collection of helpers and ready-made abstractions for react-three-fiber, covering cameras, controls, gizmos, loaders, shaders, and utilities such as Html. It is installed as @react-three/drei and used through named imports.
How do I install drei?
Run `npm install @react-three/drei`, then import the components you need from '@react-three/drei'.
Does drei work in React Native?
There is a separate route for it, imported as '@react-three/drei/native', mapped to native/index.cjs.js in package.json. That route does not export Html or Loader, while the default web export does.
Does drei include three's own addons from three/examples/jsm?
No. The project states that it uses the stand-alone three-stdlib package instead of three/examples/jsm, so addon classes arrive through that dependency rather than from the three package.
Which drei version should I install?
Check the npm tag rather than the repository, because the repository package.json is private with the version 0.0.0-semantic-release. Recent tags include v10.7.9 from 2026-09-25 and v11.0.0-alpha.7 from 2026-09-05, so a major line and its alpha are shipping together.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/pmndrs-drei)Star history chart for your README
[](https://hysenlabs.com/projects/pmndrs-drei)Was this useful?