0
# Abstractions
1

2
High-level components for common 3D elements like text, images, audio, and geometric shapes. These components provide easy-to-use interfaces for complex Three.js functionality.
3

4
## Capabilities
5

6
### Text
7

8
2D text rendering with font support, alignment options, and material properties.
9

10
```typescript { .api }
11
/**
12
 * 2D text rendering with font support
13
 * @param props - Text configuration props
14
 * @returns JSX element for the text mesh
15
 */
16
function Text(props: TextProps): JSX.Element;
17

18
interface TextProps extends Omit<ThreeElements['mesh'], 'ref'> {
19
  /** Text content */
20
  children: React.ReactNode;
21
  /** Characters to preload for performance */
22
  characters?: string;
23
  /** Text color */
24
  color?: ReactThreeFiber.Color;
25
  /** Font size, 1 */
26
  fontSize?: number;
27
  /** Font weight */
28
  fontWeight?: number | string;
29
  /** Font style */
30
  fontStyle?: 'italic' | 'normal';
31
  /** Maximum width before wrapping */
32
  maxWidth?: number;
33
  /** Line height multiplier */
34
  lineHeight?: number;
35
  /** Letter spacing */
36
  letterSpacing?: number;
37
  /** Text alignment */
38
  textAlign?: 'left' | 'right' | 'center' | 'justify';
39
  /** Font URL or data */
40
  font?: string;
41
  /** Anchor X position, 'center' */
42
  anchorX?: number | 'left' | 'center' | 'right';
43
  /** Anchor Y position, 'middle' */
44
  anchorY?: number | 'top' | 'top-baseline' | 'middle' | 'bottom-baseline' | 'bottom';
45
  /** Clip bounding box */
46
  clipRect?: [number, number, number, number];
47
  /** Depth offset for z-fighting, 0 */
48
  depthOffset?: number;
49
  /** Text direction, 'auto' */
50
  direction?: 'auto' | 'ltr' | 'rtl';
51
  /** Overflow wrapping */
52
  overflowWrap?: 'normal' | 'break-word';
53
  /** White space handling */
54
  whiteSpace?: 'normal' | 'overflowWrap' | 'nowrap';
55
  /** Outline width */
56
  outlineWidth?: number | string;
57
  /** Outline X offset */
58
  outlineOffsetX?: number | string;
59
  /** Outline Y offset */
60
  outlineOffsetY?: number | string;
61
  /** Outline blur */
62
  outlineBlur?: number | string;
63
  /** Outline color */
64
  outlineColor?: ReactThreeFiber.Color;
65
  /** Outline opacity, 1 */
66
  outlineOpacity?: number;
67
  /** Stroke width */
68
  strokeWidth?: number | string;
69
  /** Stroke color */
70
  strokeColor?: ReactThreeFiber.Color;
71
  /** Stroke opacity, 1 */
72
  strokeOpacity?: number;
73
  /** Fill opacity, 1 */
74
  fillOpacity?: number;
75
  /** SDF glyph size, 64 */
76
  sdfGlyphSize?: number;
77
  /** Enable SDF debugging */
78
  debugSDF?: boolean;
79
  /** Glyph geometry detail */
80
  glyphGeometryDetail?: number;
81
  /** Sync callback */
82
  onSync?: (troika: any) => void;
83
}
84
```
85

86
**Usage Examples:**
87

88
```typescript
89
import { Text } from '@react-three/drei';
90

91
// Basic text
92
<Text fontSize={2} color="hotpink">
93
  Hello World
94
</Text>
95

96
// Advanced text with styling
97
<Text
98
  fontSize={1}
99
  color="#333"
100
  font="/fonts/roboto.json"
101
  textAlign="center"
102
  anchorX="center"
103
  anchorY="middle"
104
  maxWidth={10}
105
  lineHeight={1.2}
106
  letterSpacing={0.1}
107
  outlineWidth={0.05}
108
  outlineColor="white"
109
>
110
  Styled Text with Outline
111
</Text>
112
```
113

114
### Text3D
115

116
3D extruded text with depth and bevel options.
117

118
```typescript { .api }
119
/**
120
 * 3D extruded text rendering
121
 * @param props - 3D text configuration props
122
 * @returns JSX element for the 3D text mesh
123
 */
124
function Text3D(props: Text3DProps): JSX.Element;
125

126
interface Text3DProps extends Omit<ThreeElements['mesh'], 'ref'> {
127
  /** Text content */
128
  children: React.ReactNode;
129
  /** Font URL or font object */
130
  font: string | FontData;
131
  /** Font size, 1 */
132
  size?: number;
133
  /** Extrusion depth, 0.2 */
134
  height?: number;
135
  /** Curve segments, 12 */
136
  curveSegments?: number;
137
  /** Enable bevel, false */
138
  bevelEnabled?: boolean;
139
  /** Bevel thickness, 0.1 */
140
  bevelThickness?: number;
141
  /** Bevel size, 0.05 */
142
  bevelSize?: number;
143
  /** Bevel offset, 0 */
144
  bevelOffset?: number;
145
  /** Bevel segments, 3 */
146
  bevelSegments?: number;
147
  /** Line height, 1 */
148
  lineHeight?: number;
149
  /** Letter spacing, 0 */
150
  letterSpacing?: number;
151
  /** Smooth rendering, false */
152
  smooth?: number;
153
}
154
```
155

156
**Usage Examples:**
157

158
```typescript
159
import { Text3D } from '@react-three/drei';
160

161
// Basic 3D text
162
<Text3D font="/fonts/helvetiker_regular.json">
163
  3D Text
164
  <meshNormalMaterial />
165
</Text3D>
166

167
// 3D text with bevel
168
<Text3D
169
  font="/fonts/helvetiker_bold.json"
170
  size={2}
171
  height={0.5}
172
  bevelEnabled
173
  bevelThickness={0.1}
174
  bevelSize={0.05}
175
  bevelSegments={5}
176
  curveSegments={8}
177
>
178
  Beveled Text
179
  <meshStandardMaterial color="gold" />
180
</Text3D>
181
```
182

183
### Image
184

185
Image display component with transparency support and aspect ratio management.
186

187
```typescript { .api }
188
/**
189
 * Image display with transparency support
190
 * @param props - Image configuration props
191
 * @returns JSX element for the image plane
192
 */
193
function Image(props: ImageProps): JSX.Element;
194

195
interface ImageProps extends Omit<ThreeElements['mesh'], 'ref'> {
196
  /** Image URL or texture */
197
  url?: string;
198
  /** Image texture */
199
  texture?: Texture;
200
  /** Image segments [x, y], [1, 1] */
201
  segments?: [number, number];
202
  /** Image scale */
203
  scale?: number | [number, number];
204
  /** Image color */
205
  color?: ReactThreeFiber.Color;
206
  /** Image opacity, 1 */
207
  opacity?: number;
208
  /** Transparent rendering, true */
209
  transparent?: boolean;
210
  /** Side rendering, FrontSide */
211
  side?: Side;
212
  /** Zoom factor, 1 */
213
  zoom?: number;
214
  /** Radius for rounded corners, 0 */
215
  radius?: number;
216
  /** Grayscale amount, 0 */
217
  grayscale?: number;
218
  /** Tone mapping, false */
219
  toneMapped?: boolean;
220
}
221
```
222

223
**Usage Examples:**
224

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

228
// Basic image
229
<Image url="/textures/photo.jpg" />
230

231
// Styled image with effects
232
<Image
233
  url="/textures/logo.png"
234
  scale={[2, 1]}
235
  opacity={0.8}
236
  transparent
237
  radius={0.1}
238
  grayscale={0.3}
239
  position={[0, 1, 0]}
240
/>
241
```
242

243
### PositionalAudio
244

245
3D positional audio component with distance-based volume and directional sound.
246

247
```typescript { .api }
248
/**
249
 * 3D positional audio with distance-based volume
250
 * @param props - Positional audio configuration
251
 * @returns JSX element for the audio source
252
 */
253
function PositionalAudio(props: PositionalAudioProps): JSX.Element;
254

255
interface PositionalAudioProps extends Omit<ThreeElements['positionalAudio'], 'ref'> {
256
  /** Audio URL or buffer */
257
  url: string | AudioBuffer;
258
  /** Audio distance model, 'inverse' */
259
  distanceModel?: 'linear' | 'inverse' | 'exponential';
260
  /** Maximum audio distance, 10000 */
261
  maxDistance?: number;
262
  /** Reference distance, 1 */
263
  refDistance?: number;
264
  /** Rolloff factor, 1 */
265
  rolloffFactor?: number;
266
  /** Inner cone angle, 360 */
267
  coneInnerAngle?: number;
268
  /** Outer cone angle, 0 */
269
  coneOuterAngle?: number;
270
  /** Outer cone gain, 0 */
271
  coneOuterGain?: number;
272
  /** Audio volume, 1 */
273
  volume?: number;
274
  /** Auto-play audio, false */
275
  autoplay?: boolean;
276
  /** Loop audio, false */
277
  loop?: boolean;
278
  /** Helper visualization, false */
279
  helper?: boolean;
280
  /** Load event handler */
281
  onLoad?: (audio: PositionalAudio) => void;
282
  /** Progress event handler */
283
  onProgress?: (event: ProgressEvent) => void;
284
  /** Error event handler */
285
  onError?: (error: ErrorEvent) => void;
286
}
287
```
288

289
**Usage Examples:**
290

291
```typescript
292
import { PositionalAudio } from '@react-three/drei';
293

294
// Basic positional audio
295
<PositionalAudio
296
  url="/audio/ambient.mp3"
297
  distance={5}
298
  loop
299
  volume={0.5}
300
/>
301

302
// Directional audio with cone
303
<PositionalAudio
304
  url="/audio/speech.wav"
305
  distanceModel="linear"
306
  maxDistance={20}
307
  refDistance={1}
308
  rolloffFactor={2}
309
  coneInnerAngle={90}
310
  coneOuterAngle={180}
311
  coneOuterGain={0.1}
312
  helper
313
  onLoad={(audio) => console.log('Audio loaded', audio)}
314
/>
315
```
316

317
### Billboard
318

319
Component that always faces the camera, useful for labels, sprites, and UI elements.
320

321
```typescript { .api }
322
/**
323
 * Component that always faces the camera
324
 * @param props - Billboard configuration props
325
 * @returns JSX element that rotates to face camera
326
 */
327
function Billboard(props: BillboardProps): JSX.Element;
328

329
interface BillboardProps extends Omit<ThreeElements['group'], 'ref'> {
330
  /** Follow mode: true, 'x', 'y', 'z' */
331
  follow?: boolean | 'x' | 'y' | 'z';
332
  /** Lock X axis, false */
333
  lockX?: boolean;
334
  /** Lock Y axis, false */
335
  lockY?: boolean;
336
  /** Lock Z axis, false */
337
  lockZ?: boolean;
338
}
339
```
340

341
**Usage Examples:**
342

343
```typescript
344
import { Billboard, Text } from '@react-three/drei';
345

346
// Text that always faces camera
347
<Billboard>
348
  <Text fontSize={1} color="white">
349
    Label
350
  </Text>
351
</Billboard>
352

353
// Billboard with axis constraints
354
<Billboard follow="y" lockX>
355
  <mesh>
356
    <planeGeometry args={[2, 1]} />
357
    <meshBasicMaterial color="red" />
358
  </mesh>
359
</Billboard>
360
```
361

362
### Line Components
363

364
Various line rendering components for curves and paths.
365

366
```typescript { .api }
367
/**
368
 * Generic line rendering component
369
 * @param props - Line configuration props
370
 * @returns JSX element for the line
371
 */
372
function Line(props: LineProps): JSX.Element;
373

374
/**
375
 * Quadratic Bezier curve line
376
 * @param props - Quadratic Bezier line props
377
 * @returns JSX element for the curve
378
 */
379
function QuadraticBezierLine(props: QuadraticBezierLineProps): JSX.Element;
380

381
/**
382
 * Cubic Bezier curve line
383
 * @param props - Cubic Bezier line props
384
 * @returns JSX element for the curve
385
 */
386
function CubicBezierLine(props: CubicBezierLineProps): JSX.Element;
387

388
/**
389
 * Catmull-Rom spline line
390
 * @param props - Catmull-Rom line props
391
 * @returns JSX element for the spline
392
 */
393
function CatmullRomLine(props: CatmullRomLineProps): JSX.Element;
394

395
interface LineProps extends Omit<ThreeElements['line'], 'ref'> {
396
  /** Line points */
397
  points: Vector3[] | [number, number, number][];
398
  /** Line color */
399
  color?: ReactThreeFiber.Color;
400
  /** Line width, 1 */
401
  lineWidth?: number;
402
  /** Dashed line pattern */
403
  dashed?: boolean;
404
  /** Dash size, 1 */
405
  dashSize?: number;
406
  /** Gap size, 1 */
407
  gapSize?: number;
408
  /** Vertex colors */
409
  vertexColors?: boolean;
410
}
411

412
interface QuadraticBezierLineProps extends Omit<LineProps, 'points'> {
413
  /** Start point */
414
  start: Vector3 | [number, number, number];
415
  /** End point */
416
  end: Vector3 | [number, number, number];
417
  /** Control point */
418
  mid: Vector3 | [number, number, number];
419
  /** Curve segments, 20 */
420
  segments?: number;
421
}
422

423
interface CubicBezierLineProps extends Omit<LineProps, 'points'> {
424
  /** Start point */
425
  start: Vector3 | [number, number, number];
426
  /** End point */
427
  end: Vector3 | [number, number, number];
428
  /** First control point */
429
  midA: Vector3 | [number, number, number];
430
  /** Second control point */
431
  midB: Vector3 | [number, number, number];
432
  /** Curve segments, 20 */
433
  segments?: number;
434
}
435

436
interface CatmullRomLineProps extends Omit<LineProps, 'points'> {
437
  /** Curve points */
438
  points: Vector3[] | [number, number, number][];
439
  /** Curve type, 'centripetal' */
440
  curveType?: 'centripetal' | 'chordal' | 'catmullrom';
441
  /** Curve tension, 0.5 */
442
  tension?: number;
443
  /** Closed curve, false */
444
  closed?: boolean;
445
  /** Curve segments, 20 */
446
  segments?: number;
447
}
448
```
449

450
**Usage Examples:**
451

452
```typescript
453
import { Line, QuadraticBezierLine, CubicBezierLine, CatmullRomLine } from '@react-three/drei';
454

455
// Basic line
456
<Line
457
  points={[[0, 0, 0], [1, 1, 0], [2, 0, 0]]}
458
  color="red"
459
  lineWidth={2}
460
/>
461

462
// Quadratic Bezier curve
463
<QuadraticBezierLine
464
  start={[0, 0, 0]}
465
  end={[2, 0, 0]}
466
  mid={[1, 2, 0]}
467
  color="blue"
468
  lineWidth={3}
469
/>
470

471
// Cubic Bezier curve
472
<CubicBezierLine
473
  start={[0, 0, 0]}
474
  end={[3, 0, 0]}
475
  midA={[1, 1, 0]}
476
  midB={[2, -1, 0]}
477
  color="green"
478
  segments={50}
479
/>
480

481
// Catmull-Rom spline
482
<CatmullRomLine
483
  points={[[0, 0, 0], [1, 2, 0], [2, -1, 0], [3, 1, 0]]}
484
  curveType="centripetal"
485
  tension={0.5}
486
  color="purple"
487
  closed
488
/>
489
```
490

491
## Integration Patterns
492

493
### Combining Text and Billboard
494

495
```typescript
496
// Label that always faces camera
497
<Billboard>
498
  <Text fontSize={0.5} color="white" anchorX="center" anchorY="middle">
499
    Player Name
500
  </Text>
501
</Billboard>
502
```
503

504
### Responsive Image Scaling
505

506
```typescript
507
function ResponsiveImage({ url }) {
508
  const { viewport } = useThree();
509
  
510
  return (
511
    <Image
512
      url={url}
513
      scale={[viewport.width / 4, viewport.height / 4]}
514
    />
515
  );
516
}
517
```
518

519
### Interactive Audio
520

521
```typescript
522
function InteractiveAudio() {
523
  const [playing, setPlaying] = useState(false);
524
  const audioRef = useRef();
525
  
526
  const togglePlay = () => {
527
    if (audioRef.current) {
528
      playing ? audioRef.current.pause() : audioRef.current.play();
529
      setPlaying(!playing);
530
    }
531
  };
532
  
533
  return (
534
    <>
535
      <PositionalAudio
536
        ref={audioRef}
537
        url="/audio/music.mp3"
538
        distance={10}
539
        volume={0.7}
540
        onLoad={togglePlay}
541
      />
542
      <mesh onClick={togglePlay}>
543
        <sphereGeometry args={[0.5]} />
544
        <meshStandardMaterial color={playing ? "green" : "red"} />
545
      </mesh>
546
    </>
547
  );
548
}
549
```
550

551
### ScreenSpace
552

553
Component that positions children in screen space, following the camera.
554

555
```typescript { .api }
556
/**
557
 * Positions children in screen space, following the camera
558
 * @param props - ScreenSpace configuration props
559
 * @returns JSX element that follows camera position and rotation
560
 */
561
function ScreenSpace(props: ScreenSpaceProps): JSX.Element;
562

563
interface ScreenSpaceProps extends Omit<ThreeElements['group'], 'ref'> {
564
  /** Depth offset from camera, -1 */
565
  depth?: number;
566
}
567
```
568

569
### Effects
570

571
Post-processing effects wrapper component for shader effects.
572

573
```typescript { .api }
574
/**
575
 * Post-processing effects wrapper using EffectComposer
576
 * @param props - Effects configuration props  
577
 * @returns JSX element for effect composition
578
 */
579
function Effects(props: EffectsProps): JSX.Element;
580

581
interface EffectsProps extends Omit<ThreeElements['effectComposer'], 'ref' | 'args'> {
582
  /** Multisampling level, 8 */
583
  multisamping?: number;
584
  /** Color space */
585
  colorSpace?: ColorSpace;
586
  /** Texture data type */
587
  type?: TextureDataType;
588
  /** Render pass index, 1 */
589
  renderIndex?: number;
590
  /** Disable gamma correction, false */
591
  disableGamma?: boolean;
592
  /** Disable render pass, false */
593
  disableRenderPass?: boolean;
594
  /** Disable rendering, false */
595
  disableRender?: boolean;
596
  /** Enable depth buffer, true */
597
  depthBuffer?: boolean;
598
  /** Enable stencil buffer, false */
599
  stencilBuffer?: boolean;
600
  /** Texture anisotropy, 1 */
601
  anisotropy?: number;
602
}
603
```
604

605
### Trail
606

607
Component that creates motion trail effects behind moving objects.
608

609
```typescript { .api }
610
/**
611
 * Creates motion trail effects behind moving objects
612
 * @param props - Trail configuration props
613
 * @returns JSX element for trail rendering
614
 */
615
function Trail(props: TrailProps): JSX.Element;
616

617
interface TrailProps extends Omit<ThreeElements['mesh'], 'ref'> {
618
  /** Trail width, 0.2 */
619
  width?: number;
620
  /** Trail length, 1 */
621
  length?: number;
622
  /** Trail decay, 1 */
623
  decay?: number;
624
  /** Trail attenuation, (width) => width */
625
  attenuation?: (width: number) => number;
626
  /** Use local coordinates, false */
627
  local?: boolean;
628
  /** Target object to follow */
629
  target?: React.RefObject<Object3D>;
630
}
631
```
632

633
### Clone
634

635
Component for efficiently creating copies of existing geometries and materials.
636

637
```typescript { .api }
638
/**
639
 * Efficiently creates copies of existing geometries and materials
640
 * @param props - Clone configuration props
641
 * @returns JSX element with cloned object
642
 */
643
function Clone(props: CloneProps): JSX.Element;
644

645
interface CloneProps extends Omit<ThreeElements['group'], 'ref'> {
646
  /** Object to clone */
647
  object: Object3D;
648
  /** Clone children, false */
649
  children?: boolean;
650
  /** Transform injections */
651
  inject?: any;
652
  /** Cast shadows */
653
  castShadow?: boolean;
654
  /** Receive shadows */
655
  receiveShadow?: boolean;
656
}
657
```