0
# @react-three/drei
1

2
@react-three/drei is a comprehensive collection of useful helpers and fully functional, ready-made abstractions for react-three-fiber. It provides 100+ components enabling developers to build 3D web applications more efficiently, including cameras, controls, shapes, staging utilities, performance optimizations, loading utilities, shader materials, abstractions, gizmos, and portal systems.
3

4
## Package Information
5

6
- **Package Name**: @react-three/drei
7
- **Package Type**: npm  
8
- **Language**: TypeScript
9
- **Installation**: `npm install @react-three/drei`
10

11
## Core Imports
12

13
```typescript
14
import { OrbitControls, Text, Environment, useAnimations } from '@react-three/drei';
15
```
16

17
For React Native (excludes Html and Loader):
18

19
```typescript
20
import { OrbitControls, Text, Environment } from '@react-three/drei/native';
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { Canvas } from '@react-three/fiber';
27
import { OrbitControls, Text, Environment, PerspectiveCamera } from '@react-three/drei';
28

29
function Scene() {
30
  return (
31
    <Canvas>
32
      <PerspectiveCamera makeDefault position={[0, 0, 5]} />
33
      <OrbitControls enableDamping />
34
      <Text fontSize={1} color="hotpink">
35
        Hello 3D World
36
      </Text>
37
      <Environment preset="sunset" />
38
    </Canvas>
39
  );
40
}
41
```
42

43
## Architecture
44

45
@react-three/drei is built around several key architectural patterns:
46

47
- **React Three Fiber Integration**: All components extend R3F's declarative patterns using `useThree`, `useFrame`, and `extend`
48
- **TypeScript Safety**: Full type safety with comprehensive prop interfaces extending Three.js types
49
- **Modular Design**: Components can be imported individually for tree-shaking
50
- **Performance Optimization**: Built-in optimizations for rendering and memory management
51
- **Cross-Platform Support**: Separate web and React Native entry points
52
- **Three.js Compatibility**: Uses three-stdlib for examples and maintains compatibility with Three.js patterns
53

54
## Capabilities
55

56
### Cameras
57

58
Camera components providing different projection and rendering modes for 3D scenes.
59

60
```typescript { .api }
61
// Perspective camera with FOV-based projection
62
function PerspectiveCamera(props: PerspectiveCameraProps): JSX.Element;
63

64
// Orthographic camera with parallel projection  
65
function OrthographicCamera(props: OrthographicCameraProps): JSX.Element;
66

67
// Cube camera for environment mapping and reflections
68
function CubeCamera(props: CubeCameraProps): JSX.Element;
69

70
interface PerspectiveCameraProps extends Omit<ThreeElements['perspectiveCamera'], 'ref'> {
71
  /** Makes this camera the default camera, true */
72
  makeDefault?: boolean;
73
  /** The camera's field of view, 75 */
74
  fov?: number;
75
  /** Camera position */
76
  position?: [number, number, number];
77
}
78
```
79

80
[Cameras](./cameras.md)
81

82
### Controls
83

84
Camera and interaction controls for navigating and manipulating 3D scenes.
85

86
```typescript { .api }
87
// Orbit camera controls for rotating around a target
88
function OrbitControls(props: OrbitControlsProps): JSX.Element;
89

90
// Transform gizmo for object manipulation
91
function TransformControls(props: TransformControlsProps): JSX.Element;
92

93
// Advanced camera controls with smooth transitions
94
function CameraControls(props: CameraControlsProps): JSX.Element;
95

96
interface OrbitControlsProps extends Omit<ThreeElement<OrbitControlsImpl>, 'ref' | 'args'> {
97
  /** Makes this the default controls, false */
98
  makeDefault?: boolean;
99
  /** The camera to control */
100
  camera?: Camera;
101
  /** Enable damping, false */
102
  enableDamping?: boolean;
103
  /** Change event handler */
104
  onChange?: (e?: OrbitControlsChangeEvent) => void;
105
}
106
```
107

108
[Controls](./controls.md)
109

110
### Abstractions
111

112
High-level components for common 3D elements like text, images, and audio.
113

114
```typescript { .api }
115
// 2D text rendering with font support
116
function Text(props: TextProps): JSX.Element;
117

118
// 3D extruded text
119
function Text3D(props: Text3DProps): JSX.Element;
120

121
// Image display with transparency support
122
function Image(props: ImageProps): JSX.Element;
123

124
// 3D positional audio
125
function PositionalAudio(props: PositionalAudioProps): JSX.Element;
126

127
interface TextProps extends Omit<ThreeElements['mesh'], 'ref'> {
128
  /** Text content */
129
  children: React.ReactNode;
130
  /** Font size, 1 */
131
  fontSize?: number;
132
  /** Text color */
133
  color?: ReactThreeFiber.Color;
134
  /** Font URL or font object */
135
  font?: string | FontData;
136
  /** Text alignment, 'left' */
137
  textAlign?: 'left' | 'right' | 'center' | 'justify';
138
}
139
```
140

141
[Abstractions](./abstractions.md)
142

143
### Materials
144

145
Shader materials for advanced visual effects and surface properties.
146

147
```typescript { .api }
148
// Mirror reflection material with blur and resolution control
149
function MeshReflectorMaterial(props: MeshReflectorMaterialProps): JSX.Element;
150

151
// Glass transmission material with thickness and roughness
152
function MeshTransmissionMaterial(props: MeshTransmissionMaterialProps): JSX.Element;
153

154
// Vertex distortion material with noise-based deformation
155
function MeshDistortMaterial(props: MeshDistortMaterialProps): JSX.Element;
156

157
interface MeshReflectorMaterialProps extends MaterialProps {
158
  /** Reflection resolution, 256 */
159
  resolution?: number;
160
  /** Blur amount [horizontal, vertical], [0, 0] */
161
  blur?: [number, number] | number;
162
  /** Mix with original material, 0 */
163
  mixBlur?: number;
164
  /** Mirror reflectivity, 0 */
165
  mirror?: number;
166
}
167
```
168

169
[Materials](./materials.md)
170

171
### Staging
172

173
Lighting, environment, and scene setup components for realistic rendering.
174

175
```typescript { .api }
176
// Environment mapping and HDRI support
177
function Environment(props: EnvironmentProps): JSX.Element;
178

179
// Contact shadows for grounded objects
180
function ContactShadows(props: ContactShadowsProps): JSX.Element;
181

182
// Studio-style lighting setup
183
function Stage(props: StageProps): JSX.Element;
184

185
// Sky dome rendering
186
function Sky(props: SkyProps): JSX.Element;
187

188
interface EnvironmentProps {
189
  /** Environment preset name */
190
  preset?: PresetsType;
191
  /** Custom environment map files */
192
  files?: string | string[];
193
  /** Environment map path */
194
  path?: string;
195
  /** Skybox rendering, false */
196
  background?: boolean;
197
  /** Ground projection, false */
198
  ground?: boolean;
199
}
200
```
201

202
[Staging](./staging.md)
203

204
### Performance
205

206
Optimization components for efficient rendering of large datasets and complex scenes.
207

208
```typescript { .api }
209
// Instanced mesh rendering for identical objects
210
function Instances(props: InstancesProps): JSX.Element;
211

212
// Point cloud rendering with efficient GPU processing
213
function Points(props: PointsProps): JSX.Element;
214

215
// Level-of-detail rendering based on distance
216
function Detailed(props: DetailedProps): JSX.Element;
217

218
// Performance monitoring with automatic degradation
219
function PerformanceMonitor(props: PerformanceMonitorProps): JSX.Element;
220

221
interface InstancesProps extends Omit<ThreeElements['instancedMesh'], 'ref' | 'args'> {
222
  /** Maximum number of instances */
223
  limit?: number;
224
  /** Instance range [start, count] */
225
  range?: [number, number];
226
  /** Frustum culling, true */
227
  frustumCulled?: boolean;
228
}
229
```
230

231
[Performance](./performance.md)
232

233
### Gizmos
234

235
Interactive tools and visual helpers for development and user interaction.
236

237
```typescript { .api }
238
// Interactive pivot controls for object transformation
239
function PivotControls(props: PivotControlsProps): JSX.Element;
240

241
// Drag controls for object manipulation
242
function DragControls(props: DragControlsProps): JSX.Element;
243

244
// 3D grid helper
245
function Grid(props: GridProps): JSX.Element;
246

247
// 3D viewcube gizmo
248
function GizmoViewcube(props: GizmoViewcubeProps): JSX.Element;
249

250
interface PivotControlsProps {
251
  /** Enable/disable controls, true */
252
  enabled?: boolean;
253
  /** Gizmo scale, 1 */
254
  scale?: number;
255
  /** Line width, 2.5 */
256
  lineWidth?: number;
257
  /** Fixed screen size, false */
258
  fixed?: boolean;
259
  /** Position offset */
260
  offset?: [number, number, number];
261
}
262
```
263

264
[Gizmos](./gizmos.md)
265

266
### Web Integration
267

268
Web-specific components for HTML overlays and browser integration.
269

270
```typescript { .api }
271
// HTML overlay integration with 3D positioning
272
function Html(props: HtmlProps): JSX.Element;
273

274
// Scroll-based camera controls
275
function ScrollControls(props: ScrollControlsProps): JSX.Element;
276

277
// Loading UI component
278
function Loader(props: LoaderProps): JSX.Element;
279

280
// Cursor style hook
281
function useCursor(hovered: boolean, cursor?: string): void;
282

283
interface HtmlProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'ref'> {
284
  /** Transform with object, false */
285
  transform?: boolean;
286
  /** Render as sprite, false */
287
  sprite?: boolean;
288
  /** Occlusion objects */
289
  occlude?: React.RefObject<Object3D>[] | boolean;
290
  /** Center content, false */
291
  center?: boolean;
292
}
293
```
294

295
[Web Integration](./web-integration.md)
296

297
### Loaders
298

299
Asset loading utilities for textures, models, and media.
300

301
```typescript { .api }
302
// Font loading hook
303
function useFont(path: string): FontData;
304

305
// GLTF model loading hook
306
function useGLTF(path: string): GLTF & ObjectMap;
307

308
// Texture loading with format support
309
function useTexture(input: string | string[]): Texture | Texture[];
310

311
// Environment texture loading
312
function useEnvironment(props: EnvironmentLoaderProps): Texture;
313

314
interface FontData {
315
  data: any;
316
  glyphs: { [key: string]: Glyph };
317
}
318

319
interface Glyph {
320
  x: number;
321
  y: number;
322
  width: number;
323
  height: number;
324
}
325
```
326

327
[Loaders](./loaders.md)
328

329
### Hooks
330

331
React hooks for animations, state management, and Three.js integration.
332

333
```typescript { .api }
334
// Animation control hook
335
function useAnimations<T extends AnimationClip>(
336
  clips: T[],
337
  root?: React.RefObject<Object3D>
338
): Api<T>;
339

340
// Aspect ratio calculation hook
341
function useAspect(width: number, height: number, factor?: number): [number, number, number];
342

343
// Camera hook for accessing current camera
344
function useCamera(): Camera;
345

346
// Intersection detection hook  
347
function useIntersect<T extends Object3D>(
348
  onChange: (visible: boolean) => void
349
): React.RefObject<T>;
350

351
interface Api<T extends AnimationClip> {
352
  ref: React.RefObject<Object3D>;
353
  clips: AnimationClip[];
354
  mixer: AnimationMixer;
355
  names: T['name'][];
356
  actions: { [key in T['name']]: AnimationAction | null };
357
}
358
```
359

360
[Hooks](./hooks.md)
361

362
## Types
363

364
Core TypeScript types and interfaces used throughout the library.
365

366
```typescript { .api }
367
// Utility type for component props with forwardRef
368
type ForwardRefComponent<P, T> = ForwardRefExoticComponent<PropsWithoutRef<P> & RefAttributes<T>>;
369

370
// Type overwriting utility
371
type Overwrite<T, O> = Omit<T, NonFunctionKeys<O>> & O;
372

373
// Environment preset names
374
type PresetsType = 'apartment' | 'city' | 'dawn' | 'forest' | 'lobby' | 'night' | 'park' | 'studio' | 'sunset' | 'warehouse';
375

376
// Gradient texture types
377
enum GradientType {
378
  Linear = 'linear',
379
  Radial = 'radial'
380
}
381

382
// Material base properties
383
interface MaterialProps extends Omit<ThreeElements['material'], 'ref'> {
384
  opacity?: number;
385
  transparent?: boolean;
386
  color?: ReactThreeFiber.Color;
387
}
388
```
389

390
## Dependencies
391

392
@react-three/drei requires the following peer dependencies:
393

394
- `@react-three/fiber` ^9.0.0 - React Three.js renderer
395
- `react` ^19 - React framework  
396
- `react-dom` ^19 - React DOM (optional for React Native)
397
- `three` >=0.159 - Three.js 3D library
398

399
Key internal dependencies include `three-stdlib`, `camera-controls`, `three-mesh-bvh`, and `troika-three-text` for enhanced functionality.