0
# Materials
1

2
Shader materials for advanced visual effects and surface properties. These materials extend Three.js capabilities with custom shaders for realistic lighting, distortion effects, and specialized rendering techniques.
3

4
## Capabilities
5

6
### MeshReflectorMaterial
7

8
Mirror reflection material with blur control, resolution settings, and realistic reflections.
9

10
```typescript { .api }
11
/**
12
 * Mirror reflection material with blur and resolution control
13
 * @param props - Reflector material configuration
14
 * @returns JSX element for the reflector material
15
 */
16
function MeshReflectorMaterial(props: MeshReflectorMaterialProps): JSX.Element;
17

18
interface MeshReflectorMaterialProps extends MaterialProps {
19
  /** Reflection resolution, 256 */
20
  resolution?: number;
21
  /** Blur amount [horizontal, vertical], [0, 0] */
22
  blur?: [number, number] | number;
23
  /** Mix with original material, 0 */
24
  mixBlur?: number;
25
  /** Mirror reflectivity, 0 */
26
  mirror?: number;
27
  /** Minimum blur amount, 0 */
28
  minDepthThreshold?: number;
29
  /** Maximum blur amount, 1 */
30
  maxDepthThreshold?: number;
31
  /** Depth scale, 0 */
32
  depthScale?: number;
33
  /** Depth to blur ratio, 0.25 */
34
  depthToBlurRatioBias?: number;
35
  /** Distortion map */
36
  distortion?: number;
37
  /** Distortion texture */
38
  distortionMap?: Texture;
39
  /** Fresnel coefficient, 0 */
40
  mixContrast?: number;
41
  /** Reflection roughness, 0 */
42
  roughness?: number;
43
  /** Reflection metalness, 0 */
44
  metalness?: number;
45
  /** Normal map */
46
  normalMap?: Texture;
47
  /** Normal scale, [1, 1] */
48
  normalScale?: [number, number];
49
  /** Plane normal, [0, 1, 0] */
50
  planeNormal?: [number, number, number];
51
}
52
```
53

54
**Usage Examples:**
55

56
```typescript
57
import { MeshReflectorMaterial } from '@react-three/drei';
58

59
// Basic mirror floor
60
<mesh rotation={[-Math.PI / 2, 0, 0]} position={[0, -1, 0]}>
61
  <planeGeometry args={[10, 10]} />
62
  <MeshReflectorMaterial
63
    blur={[300, 100]}
64
    resolution={2048}
65
    mixBlur={1}
66
    mixStrength={40}
67
    roughness={1}
68
    depthScale={1.2}
69
    minDepthThreshold={0.4}
70
    maxDepthThreshold={1.4}
71
    color="#050505"
72
    metalness={0.5}
73
  />
74
</mesh>
75

76
// Water reflection
77
<mesh>
78
  <planeGeometry args={[20, 20]} />
79
  <MeshReflectorMaterial
80
    resolution={1024}
81
    blur={[512, 512]}
82
    mixBlur={0.15}
83
    mirror={0.5}
84
    color="#1e4d72"
85
    roughness={0.6}
86
    normalMap={waterNormalTexture}
87
    normalScale={[0.15, 0.15]}
88
  />
89
</mesh>
90
```
91

92
### MeshTransmissionMaterial
93

94
Glass transmission material with thickness control, roughness, and realistic light transmission.
95

96
```typescript { .api }
97
/**
98
 * Glass transmission material with thickness and roughness control
99
 * @param props - Transmission material configuration
100
 * @returns JSX element for the transmission material
101
 */
102
function MeshTransmissionMaterial(props: MeshTransmissionMaterialProps): JSX.Element;
103

104
interface MeshTransmissionMaterialProps extends MaterialProps {
105
  /** Material thickness, 0 */
106
  thickness?: number;
107
  /** Roughness, 0 */
108
  roughness?: number;
109
  /** Transmission, 1 */
110
  transmission?: number;
111
  /** Index of refraction, 1.5 */
112
  ior?: number;
113
  /** Chromatic aberration, 0.03 */
114
  chromaticAberration?: number;
115
  /** Anisotropic blur, 0.1 */
116
  anisotropicBlur?: number;
117
  /** Distortion, 0 */
118
  distortion?: number;
119
  /** Distortion scale, 1 */
120
  distortionScale?: number;
121
  /** Temporal distortion, 0 */
122
  temporalDistortion?: number;
123
  /** Buffer resolution, 2048 */
124
  buffer?: number;
125
  /** Background color */
126
  background?: Texture;
127
  /** Background blur, 0 */
128
  backside?: boolean;
129
  /** Sample count, 10 */
130
  samples?: number;
131
  /** Resolution, 2048 */
132
  resolution?: number;
133
  /** Clearcoat, 1 */
134
  clearcoat?: number;
135
  /** Clearcoat roughness, 0 */
136
  clearcoatRoughness?: number;
137
  /** Clearcoat normal map */
138
  clearcoatNormalMap?: Texture;
139
  /** Clearcoat normal scale, [1, 1] */
140
  clearcoatNormalScale?: [number, number];
141
  /** Attenuation color, white */
142
  attenuationColor?: ReactThreeFiber.Color;
143
  /** Attenuation distance, Infinity */
144
  attenuationDistance?: number;
145
}
146
```
147

148
**Usage Examples:**
149

150
```typescript
151
import { MeshTransmissionMaterial } from '@react-three/drei';
152

153
// Basic glass sphere
154
<mesh>
155
  <sphereGeometry />
156
  <MeshTransmissionMaterial
157
    thickness={2}
158
    roughness={0}
159
    transmission={1}
160
    ior={1.5}
161
    chromaticAberration={0.02}
162
    backside
163
  />
164
</mesh>
165

166
// Advanced glass material
167
<mesh>
168
  <torusGeometry args={[1, 0.4, 16, 100]} />
169
  <MeshTransmissionMaterial
170
    thickness={0.2}
171
    roughness={0.4}
172
    transmission={1}
173
    ior={1.2}
174
    chromaticAberration={0.02}
175
    anisotropicBlur={0.1}
176
    distortion={0.0}
177
    distortionScale={0.3}
178
    temporalDistortion={0.5}
179
    clearcoat={1}
180
    attenuationDistance={0.5}
181
    attenuationColor="#ffffff"
182
    color="#c9ffa1"
183
    bg={backgroundTexture}
184
  />
185
</mesh>
186
```
187

188
### MeshDistortMaterial
189

190
Vertex distortion material with noise-based deformation and animation support.
191

192
```typescript { .api }
193
/**
194
 * Vertex distortion material with noise-based deformation
195
 * @param props - Distort material configuration
196
 * @returns JSX element for the distortion material
197
 */
198
function MeshDistortMaterial(props: MeshDistortMaterialProps): JSX.Element;
199

200
interface MeshDistortMaterialProps extends MaterialProps {
201
  /** Distortion strength, 1 */
202
  distort?: number;
203
  /** Animation speed, 1 */
204
  speed?: number;
205
  /** Noise frequency, 0.4 */
206
  factor?: number;
207
  /** Time offset, 0 */
208
  time?: number;
209
  /** Noise radius, 1 */
210
  radius?: number;
211
}
212
```
213

214
**Usage Examples:**
215

216
```typescript
217
import { MeshDistortMaterial } from '@react-three/drei';
218

219
// Animated distorted sphere
220
<mesh>
221
  <sphereGeometry args={[1, 64, 64]} />
222
  <MeshDistortMaterial
223
    color="#ff6090"
224
    distort={0.3}
225
    speed={2}
226
    roughness={0.4}
227
  />
228
</mesh>
229

230
// Custom distortion
231
<mesh>
232
  <planeGeometry args={[4, 4, 32, 32]} />
233
  <MeshDistortMaterial
234
    color="#8844aa"
235
    distort={0.6}
236
    speed={1.5}
237
    factor={0.2}
238
    metalness={0.1}
239
    roughness={0.75}
240
  />
241
</mesh>
242
```
243

244
### MeshWobbleMaterial
245

246
Wobble deformation material creating wave-like surface animations.
247

248
```typescript { .api }
249
/**
250
 * Wobble deformation material for wave-like animations
251
 * @param props - Wobble material configuration
252
 * @returns JSX element for the wobble material
253
 */
254
function MeshWobbleMaterial(props: MeshWobbleMaterialProps): JSX.Element;
255

256
interface MeshWobbleMaterialProps extends MaterialProps {
257
  /** Wobble strength, 1 */
258
  factor?: number;
259
  /** Animation speed, 1 */
260
  speed?: number;
261
  /** Time offset, 0 */
262
  time?: number;
263
}
264
```
265

266
**Usage Examples:**
267

268
```typescript
269
import { MeshWobbleMaterial } from '@react-three/drei';
270

271
// Wobbling box
272
<mesh>
273
  <boxGeometry args={[2, 2, 2, 32, 32, 32]} />
274
  <MeshWobbleMaterial
275
    color="hotpink"
276
    factor={1}
277
    speed={2}
278
  />
279
</mesh>
280
```
281

282
### MeshRefractionMaterial
283

284
Refraction material for crystal and glass-like effects with environment mapping.
285

286
```typescript { .api }
287
/**
288
 * Refraction material for crystal and glass effects
289
 * @param props - Refraction material configuration
290
 * @returns JSX element for the refraction material
291
 */
292
function MeshRefractionMaterial(props: MeshRefractionMaterialProps): JSX.Element;
293

294
interface MeshRefractionMaterialProps extends MaterialProps {
295
  /** Environment map */
296
  envMap: Texture;
297
  /** Bounces for internal reflections, 3 */
298
  bounces?: number;
299
  /** Index of refraction, 2.4 */
300
  ior?: number;
301
  /** Fresnel bias, 0 */
302
  fresnel?: number;
303
  /** Aberration strength, 0.01 */
304
  aberrationStrength?: number;
305
  /** Fast chroma, true */
306
  fastChroma?: boolean;
307
}
308
```
309

310
### MeshDiscardMaterial
311

312
Alpha discard material for cutout effects and transparency.
313

314
```typescript { .api }
315
/**
316
 * Alpha discard material for cutout effects
317
 * @param props - Discard material configuration
318
 * @returns JSX element for the discard material
319
 */
320
function MeshDiscardMaterial(props: MeshDiscardMaterialProps): JSX.Element;
321

322
interface MeshDiscardMaterialProps extends MaterialProps {
323
  /** Alpha threshold, 0.1 */
324
  threshold?: number;
325
}
326
```
327

328
### PointMaterial
329

330
Specialized material for point cloud rendering with size and color control.
331

332
```typescript { .api }
333
/**
334
 * Point cloud material with size and color control
335
 * @param props - Point material configuration
336
 * @returns JSX element for the point material
337
 */
338
function PointMaterial(props: PointMaterialProps): JSX.Element;
339

340
interface PointMaterialProps extends MaterialProps {
341
  /** Point size, 1 */
342
  size?: number;
343
  /** Size attenuation, true */
344
  sizeAttenuation?: boolean;
345
  /** Vertex colors, false */
346
  vertexColors?: boolean;
347
  /** Alpha test, 0 */
348
  alphaTest?: number;
349
  /** Alpha map */
350
  alphaMap?: Texture;
351
}
352
```
353

354
### MultiMaterial
355

356
Material that applies different materials to different faces of a geometry.
357

358
```typescript { .api }
359
/**
360
 * Multi-material for applying different materials to geometry faces
361
 * @param props - Multi-material configuration
362
 * @returns JSX element for the multi-material
363
 */
364
function MultiMaterial(props: MultiMaterialProps): JSX.Element;
365

366
interface MultiMaterialProps extends Omit<ThreeElements['group'], 'ref'> {
367
  /** Array of materials to apply */
368
  materials: Material[];
369
}
370
```
371

372
### shaderMaterial
373

374
Utility function for creating custom shader materials with TypeScript support.
375

376
```typescript { .api }
377
/**
378
 * Utility function for creating custom shader materials
379
 * @param uniforms - Shader uniforms object
380
 * @param vertexShader - Vertex shader source
381
 * @param fragmentShader - Fragment shader source
382
 * @returns Custom shader material class
383
 */
384
function shaderMaterial(
385
  uniforms: { [key: string]: { value: any } },
386
  vertexShader: string,
387
  fragmentShader: string
388
): typeof Material;
389
```
390

391
**Usage Examples:**
392

393
```typescript
394
import { shaderMaterial } from '@react-three/drei';
395
import { extend } from '@react-three/fiber';
396

397
// Create custom material
398
const CustomMaterial = shaderMaterial(
399
  {
400
    time: { value: 0 },
401
    color: { value: new Color('#ff0000') }
402
  },
403
  // Vertex shader
404
  `
405
    varying vec2 vUv;
406
    void main() {
407
      vUv = uv;
408
      gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
409
    }
410
  `,
411
  // Fragment shader
412
  `
413
    uniform float time;
414
    uniform vec3 color;
415
    varying vec2 vUv;
416
    void main() {
417
      float strength = sin(vUv.x * 10.0 + time) * 0.5 + 0.5;
418
      gl_FragColor = vec4(color * strength, 1.0);
419
    }
420
  `
421
);
422

423
// Extend for React Three Fiber
424
extend({ CustomMaterial });
425

426
// Use in component
427
<mesh>
428
  <planeGeometry />
429
  <customMaterial time={clock.elapsedTime} color="#00ff00" />
430
</mesh>
431
```
432

433
## Integration Patterns
434

435
### Material Animation
436

437
Materials can be animated using `useFrame`:
438

439
```typescript
440
import { useFrame } from '@react-three/fiber';
441

442
function AnimatedMaterial() {
443
  const materialRef = useRef();
444
  
445
  useFrame((state) => {
446
    if (materialRef.current) {
447
      materialRef.current.time = state.clock.elapsedTime;
448
    }
449
  });
450
  
451
  return (
452
    <mesh>
453
      <sphereGeometry />
454
      <MeshDistortMaterial
455
        ref={materialRef}
456
        distort={0.3}
457
        speed={2}
458
        color="hotpink"
459
      />
460
    </mesh>
461
  );
462
}
463
```
464

465
### Environment-Dependent Materials
466

467
Some materials require environment maps:
468

469
```typescript
470
import { Environment, MeshRefractionMaterial } from '@react-three/drei';
471

472
function RefractiveObject() {
473
  const envMap = useEnvironment({ preset: 'city' });
474
  
475
  return (
476
    <>
477
      <Environment preset="city" />
478
      <mesh>
479
        <icosahedronGeometry />
480
        <MeshRefractionMaterial
481
          envMap={envMap}
482
          bounces={3}
483
          ior={2.4}
484
          aberrationStrength={0.02}
485
        />
486
      </mesh>
487
    </>
488
  );
489
}
490
```
491

492
### Performance Considerations
493

494
For optimal performance with shader materials:
495

496
```typescript
497
// Use useMemo for expensive material creation
498
const material = useMemo(() => new MeshTransmissionMaterial({
499
  thickness: 2,
500
  roughness: 0.4,
501
  transmission: 1,
502
  ior: 1.5,
503
  chromaticAberration: 0.02,
504
}), []);
505

506
// Dispose materials on unmount
507
useEffect(() => {
508
  return () => material.dispose();
509
}, [material]);
510
```