0
# Controls
1

2
Camera and interaction controls for navigating and manipulating 3D scenes. All control components integrate with React Three Fiber's camera system and provide smooth, configurable interaction patterns.
3

4
## Capabilities
5

6
### OrbitControls
7

8
Orbit camera controls for rotating around a target point, with support for zooming, panning, and damping.
9

10
```typescript { .api }
11
/**
12
 * Orbit camera controls for rotating around a target
13
 * @param props - Orbit controls configuration
14
 * @returns JSX element for the controls
15
 */
16
function OrbitControls(props: OrbitControlsProps): JSX.Element;
17

18
interface OrbitControlsProps extends Omit<ThreeElement<OrbitControlsImpl>, 'ref' | 'args'> {
19
  /** Makes this the default controls, false */
20
  makeDefault?: boolean;
21
  /** The camera to control */
22
  camera?: Camera;
23
  /** DOM element for event listeners */
24
  domElement?: HTMLElement;
25
  /** Enable damping (inertia), false */
26
  enableDamping?: boolean;
27
  /** Damping factor, 0.05 */
28
  dampingFactor?: number;
29
  /** Enable zoom, true */
30
  enableZoom?: boolean;
31
  /** Zoom speed, 1 */
32
  zoomSpeed?: number;
33
  /** Enable rotation, true */
34
  enableRotate?: boolean;
35
  /** Rotation speed, 1 */
36
  rotateSpeed?: number;
37
  /** Enable panning, true */
38
  enablePan?: boolean;
39
  /** Pan speed, 1 */
40
  panSpeed?: number;
41
  /** Auto-rotate, false */
42
  autoRotate?: boolean;
43
  /** Auto-rotate speed, 2 */
44
  autoRotateSpeed?: number;
45
  /** Minimum polar angle, 0 */
46
  minPolarAngle?: number;
47
  /** Maximum polar angle, Math.PI */
48
  maxPolarAngle?: number;
49
  /** Minimum azimuth angle */
50
  minAzimuthAngle?: number;
51
  /** Maximum azimuth angle */
52
  maxAzimuthAngle?: number;
53
  /** Minimum zoom distance, 0 */
54
  minDistance?: number;
55
  /** Maximum zoom distance, Infinity */
56
  maxDistance?: number;
57
  /** Target position */
58
  target?: Vector3;
59
  /** Change event handler */
60
  onChange?: (e?: OrbitControlsChangeEvent) => void;
61
  /** Start event handler */
62
  onStart?: (e?: OrbitControlsChangeEvent) => void;
63
  /** End event handler */
64
  onEnd?: (e?: OrbitControlsChangeEvent) => void;
65
}
66

67
interface OrbitControlsChangeEvent {
68
  target: OrbitControlsImpl;
69
  type: 'change' | 'start' | 'end';
70
}
71
```
72

73
**Usage Examples:**
74

75
```typescript
76
import { OrbitControls } from '@react-three/drei';
77

78
// Basic orbit controls
79
<OrbitControls enableDamping />
80

81
// Advanced orbit controls with constraints
82
<OrbitControls
83
  enableDamping
84
  dampingFactor={0.1}
85
  minDistance={2}
86
  maxDistance={20}
87
  minPolarAngle={Math.PI / 6}
88
  maxPolarAngle={Math.PI - Math.PI / 6}
89
  autoRotate
90
  autoRotateSpeed={0.5}
91
  onChange={(e) => console.log('Controls changed', e)}
92
/>
93
```
94

95
### TransformControls
96

97
Interactive transformation gizmo for translating, rotating, and scaling objects in 3D space.
98

99
```typescript { .api }
100
/**
101
 * Transform gizmo for object manipulation
102
 * @param props - Transform controls configuration
103
 * @returns JSX element for the transform controls
104
 */
105
function TransformControls(props: TransformControlsProps): JSX.Element;
106

107
interface TransformControlsProps extends Omit<ThreeElement<TransformControlsImpl>, 'ref' | 'args'> {
108
  /** Object to transform */
109
  object?: Object3D;
110
  /** The camera to use */
111
  camera?: Camera;
112
  /** DOM element for events */
113
  domElement?: HTMLElement;
114
  /** Control mode: 'translate' | 'rotate' | 'scale' */
115
  mode?: 'translate' | 'rotate' | 'scale';
116
  /** Transform space: 'world' | 'local' */
117
  space?: 'world' | 'local';
118
  /** Control size, 1 */
119
  size?: number;
120
  /** Show X axis, true */
121
  showX?: boolean;
122
  /** Show Y axis, true */
123
  showY?: boolean;
124
  /** Show Z axis, true */
125
  showZ?: boolean;
126
  /** Enable translation, true */
127
  translationSnap?: number;
128
  /** Enable rotation snap */
129
  rotationSnap?: number;
130
  /** Enable scale snap */
131
  scaleSnap?: number;
132
  /** Dragging event handler */
133
  onDragging?: (dragging: boolean) => void;
134
  /** Change event handler */
135
  onChange?: () => void;
136
  /** Mouse down event handler */
137
  onMouseDown?: () => void;
138
  /** Mouse up event handler */
139
  onMouseUp?: () => void;
140
}
141
```
142

143
**Usage Examples:**
144

145
```typescript
146
import { TransformControls } from '@react-three/drei';
147

148
// Basic transform controls
149
function TransformableBox() {
150
  const boxRef = useRef();
151
  
152
  return (
153
    <>
154
      <mesh ref={boxRef}>
155
        <boxGeometry />
156
        <meshStandardMaterial />
157
      </mesh>
158
      <TransformControls object={boxRef.current} />
159
    </>
160
  );
161
}
162

163
// Transform controls with constraints
164
<TransformControls
165
  object={objectRef.current}
166
  mode="translate"
167
  space="world"
168
  size={1.5}
169
  showZ={false}
170
  translationSnap={0.5}
171
  onDragging={(dragging) => {
172
    // Disable orbit controls while dragging
173
    orbitControlsRef.current.enabled = !dragging;
174
  }}
175
/>
176
```
177

178
### CameraControls
179

180
Advanced camera controls with smooth transitions, focus functionality, and programmatic animation.
181

182
```typescript { .api }
183
/**
184
 * Advanced camera controls with smooth transitions
185
 * @param props - Camera controls configuration
186
 * @returns JSX element for the camera controls
187
 */
188
function CameraControls(props: CameraControlsProps): JSX.Element;
189

190
interface CameraControlsProps extends Omit<ThreeElement<CameraControlsImpl>, 'ref' | 'args'> {
191
  /** Makes this the default controls, false */
192
  makeDefault?: boolean;
193
  /** The camera to control */
194
  camera?: Camera;
195
  /** DOM element for events */
196
  domElement?: HTMLElement;
197
  /** Smooth time for transitions, 0.25 */
198
  smoothTime?: number;
199
  /** Enable smooth dragging, true */
200
  smoothTime?: number;
201
  /** Drag smooth time, 0.25 */
202
  draggingSmoothTime?: number;
203
  /** Maximum speed, Infinity */
204
  maxSpeed?: number;
205
  /** Azimuth rotation speed, 1 */
206
  azimuthRotateSpeed?: number;
207
  /** Polar rotation speed, 1 */
208
  polarRotateSpeed?: number;
209
  /** Dolly speed, 1 */
210
  dollySpeed?: number;
211
  /** Truck speed, 2 */
212
  truckSpeed?: number;
213
  /** Enable dolly, true */
214
  dollyToCursor?: boolean;
215
  /** Dolly damping factor, 0.01 */
216
  dollyDragInverted?: boolean;
217
  /** Change event handler */
218
  onChange?: (e?: any) => void;
219
}
220

221
type CameraControls = CameraControlsImpl;
222
```
223

224
**Usage Examples:**
225

226
```typescript
227
import { CameraControls } from '@react-three/drei';
228

229
// Basic camera controls
230
<CameraControls makeDefault />
231

232
// Camera controls with smooth transitions
233
<CameraControls
234
  smoothTime={0.5}
235
  maxSpeed={10}
236
  azimuthRotateSpeed={0.3}
237
  polarRotateSpeed={0.3}
238
  dollySpeed={0.5}
239
  truckSpeed={1}
240
/>
241

242
// Programmatic camera animation
243
function AnimatedCameraControls() {
244
  const controlsRef = useRef();
245
  
246
  const focusOnObject = () => {
247
    controlsRef.current?.fitToBox(boxRef.current, true);
248
  };
249
  
250
  return (
251
    <>
252
      <CameraControls ref={controlsRef} />
253
      <button onClick={focusOnObject}>Focus on Object</button>
254
    </>
255
  );
256
}
257
```
258

259
### MapControls
260

261
Map-style controls optimized for top-down navigation, commonly used for architectural visualizations and map interfaces.
262

263
```typescript { .api }
264
/**
265
 * Map-style controls for top-down navigation
266
 * @param props - Map controls configuration
267
 * @returns JSX element for the map controls
268
 */
269
function MapControls(props: MapControlsProps): JSX.Element;
270

271
interface MapControlsProps extends Omit<ThreeElement<MapControlsImpl>, 'ref' | 'args'> {
272
  /** Makes this the default controls, false */
273
  makeDefault?: boolean;
274
  /** The camera to control */
275
  camera?: Camera;
276
  /** DOM element for events */
277
  domElement?: HTMLElement;
278
  /** Enable screen space panning, true */
279
  screenSpacePanning?: boolean;
280
  /** Enable damping, false */
281
  enableDamping?: boolean;
282
  /** Damping factor, 0.05 */
283
  dampingFactor?: number;
284
  /** Enable zoom, true */
285
  enableZoom?: boolean;
286
  /** Zoom speed, 1 */
287
  zoomSpeed?: number;
288
  /** Enable rotation, true */
289
  enableRotate?: boolean;
290
  /** Rotation speed, 1 */
291
  rotateSpeed?: number;
292
  /** Enable panning, true */
293
  enablePan?: boolean;
294
  /** Pan speed, 1 */
295
  panSpeed?: number;
296
  /** Keyboard pan speed, 7 */
297
  keyPanSpeed?: number;
298
  /** Minimum zoom distance, 0 */
299
  minDistance?: number;
300
  /** Maximum zoom distance, Infinity */
301
  maxDistance?: number;
302
  /** Target position */
303
  target?: Vector3;
304
}
305
```
306

307
### TrackballControls
308

309
Trackball-style controls providing unconstrained rotation around the scene center.
310

311
```typescript { .api }
312
/**
313
 * Trackball controls for unconstrained rotation
314
 * @param props - Trackball controls configuration
315
 * @returns JSX element for the trackball controls
316
 */
317
function TrackballControls(props: TrackballControlsProps): JSX.Element;
318

319
interface TrackballControlsProps extends Omit<ThreeElement<TrackballControlsImpl>, 'ref' | 'args'> {
320
  /** The camera to control */
321
  camera?: Camera;
322
  /** DOM element for events */
323
  domElement?: HTMLElement;
324
  /** Rotation speed, 1 */
325
  rotateSpeed?: number;
326
  /** Zoom speed, 1.2 */
327
  zoomSpeed?: number;
328
  /** Pan speed, 0.3 */
329
  panSpeed?: number;
330
  /** No rotate, false */
331
  noRotate?: boolean;
332
  /** No zoom, false */
333
  noZoom?: boolean;
334
  /** No pan, false */
335
  noPan?: boolean;
336
  /** Static moving, false */
337
  staticMoving?: boolean;
338
  /** Dynamic damping factor, 0.2 */
339
  dynamicDampingFactor?: number;
340
  /** Minimum distance, 0 */
341
  minDistance?: number;
342
  /** Maximum distance, Infinity */
343
  maxDistance?: number;
344
}
345
```
346

347
### PointerLockControls
348

349
First-person pointer lock controls for immersive camera navigation.
350

351
```typescript { .api }
352
/**
353
 * First-person pointer lock controls
354
 * @param props - Pointer lock controls configuration
355
 * @returns JSX element for the pointer lock controls
356
 */
357
function PointerLockControls(props: PointerLockControlsProps): JSX.Element;
358

359
interface PointerLockControlsProps extends Omit<ThreeElement<PointerLockControlsImpl>, 'ref' | 'args'> {
360
  /** The camera to control */
361
  camera?: Camera;
362
  /** DOM element for events */
363
  domElement?: HTMLElement;
364
  /** Minimum polar angle, 0 */
365
  minPolarAngle?: number;
366
  /** Maximum polar angle, Math.PI */
367
  maxPolarAngle?: number;
368
  /** Pointer speed, 1 */
369
  pointerSpeed?: number;
370
  /** Lock event handler */
371
  onLock?: () => void;
372
  /** Unlock event handler */
373
  onUnlock?: () => void;
374
  /** Change event handler */
375
  onChange?: (e?: any) => void;
376
}
377
```
378

379
### ArcballControls
380

381
Arcball controls providing intuitive 3D rotation with visual feedback.
382

383
```typescript { .api }
384
/**
385
 * Arcball controls for intuitive 3D rotation
386
 * @param props - Arcball controls configuration
387
 * @returns JSX element for the arcball controls
388
 */
389
function ArcballControls(props: ArcballControlsProps): JSX.Element;
390

391
interface ArcballControlsProps extends Omit<ThreeElement<ArcballControlsImpl>, 'ref' | 'args'> {
392
  /** The camera to control */
393
  camera?: Camera;
394
  /** DOM element for events */
395
  domElement?: HTMLElement;
396
  /** Cursor radius, 1 */
397
  cursorZoom?: boolean;
398
  /** Adjust near and far planes, false */
399
  adjustNearFar?: boolean;
400
  /** Scale factor, 1 */
401
  scaleFactor?: number;
402
  /** Damping factor, 20 */
403
  dampingFactor?: number;
404
  /** Enable animations, false */
405
  enableAnimations?: boolean;
406
  /** Enable grid, false */
407
  enableGrid?: boolean;
408
  /** Enable zoom, true */
409
  enableZoom?: boolean;
410
  /** Enable rotate, true */
411
  enableRotate?: boolean;
412
  /** Enable pan, true */
413
  enablePan?: boolean;
414
}
415
```
416

417
## Integration Patterns
418

419
### Making Controls Default
420

421
Any control can be made the default for the scene:
422

423
```typescript
424
// These controls will be used by other components that need controls
425
<OrbitControls makeDefault enableDamping />
426
```
427

428
### Combining Controls with Cameras
429

430
Controls automatically work with the default camera or can target specific cameras:
431

432
```typescript
433
<PerspectiveCamera makeDefault position={[0, 0, 5]} />
434
<OrbitControls /> // Uses the default camera
435

436
// Or specify a camera explicitly
437
<OrbitControls camera={customCameraRef.current} />
438
```
439

440
### Disabling Controls Temporarily
441

442
Controls can be disabled during interactions:
443

444
```typescript
445
function InteractiveScene() {
446
  const [controlsEnabled, setControlsEnabled] = useState(true);
447
  
448
  return (
449
    <>
450
      <OrbitControls enabled={controlsEnabled} />
451
      <TransformControls
452
        object={objectRef.current}
453
        onDragging={setControlsEnabled}
454
      />
455
    </>
456
  );
457
}
458
```
459

460
### Event Handling
461

462
Controls provide comprehensive event handling:
463

464
```typescript
465
<OrbitControls
466
  onChange={(e) => console.log('Camera changed')}
467
  onStart={(e) => console.log('Interaction started')}
468
  onEnd={(e) => console.log('Interaction ended')}
469
/>
470
```