React Three Fiber lighting
Check installed Three.js, Fiber, and Drei versions and the renderer first. This example targets Fiber 9 / React 19, Three.js r185, and WebGL.
Start with a deliberate lighting setup
- Use environment lighting for PBR reflections/fill and direct lights for direction and real-time shadowing. More ambient light will not restore missing metallic reflections.
- A scene background and
scene.environment serve different purposes. Drei Environment assigns lighting; background additionally makes it visible behind the scene.
- Prefer an owned HDR/EXR asset in production. Drei presets are useful for prototyping but depend on external hosting. Check loader support before choosing newer formats.
Sky is visible sky geometry, not automatically a matching sun light or environment. Align the sky, direct light, and environment when visual consistency matters.
Shadowed scene
Mount inside <Canvas shadows="percentage">. On Three.js r182+, PCFShadowMap is soft; Fiber 9's bare shadows selects the deprecated PCFSoftShadowMap.
export default function Example() {
return (
<>
<ambientLight intensity={0.3} />
<directionalLight
position={[3, 5, 3]}
intensity={3}
castShadow
shadow-mapSize={[1024, 1024]}
shadow-camera-left={-4}
shadow-camera-right={4}
shadow-camera-top={4}
shadow-camera-bottom={-4}
shadow-camera-near={0.5}
shadow-camera-far={15}
shadow-normalBias={0.02}
/>
<mesh castShadow position={[0, 0.5, 0]}>
<boxGeometry />
<meshStandardMaterial color="coral" />
</mesh>
<mesh receiveShadow rotation={[-Math.PI / 2, 0, 0]}>
<planeGeometry args={[8, 8]} />
<meshStandardMaterial color="silver" />
</mesh>
</>
)
}
Bias and frustum values above are for this small scene; retune them for actual dimensions.
Shadows and light targets
- Shadow mapping needs renderer shadows enabled, a shadow-casting light, casting meshes, and receiving materials/meshes. Ambient and hemisphere lights do not cast shadows.
- Tighten the shadow camera to the useful region before increasing map resolution. Inspect its frustum with a CameraHelper; bias should address acne without detaching shadows from objects.
- Point-light shadows render six directions. Limit shadow-casting lights and large maps; cost depends on affected geometry and passes, not just light count.
- Moving a directional/spot light's target requires a target Object3D whose world matrix updates. Add a custom target to the scene graph; changing only a detached target's position can leave its world transform stale.
- With WebGL, RectAreaLight affects Standard/Physical materials and does not cast built-in shadows. Initialize
RectAreaLightUniformsLib when using the native light path that requires it.
- Object/camera layers are not general per-light material masks in WebGLRenderer. Do not promise that matching a light layer to a mesh makes selective illumination work.
Environment and helper cost
- Drei
Lightformer is emissive geometry captured into an Environment; it is not an ordinary real-time light and does not cast direct-light shadows.
- Set
frames={1} for genuinely static environment captures or ContactShadows. Animated objects/lighting need recapture; a frozen capture will remain stale.
- ContactShadows renders an offscreen depth/blur approximation. It is not free and does not replace all directional shadows.
- AccumulativeShadows converges across samples; changing the scene can require reset/reaccumulation. BakeShadows freezes updates rather than producing a portable baked lightmap.
- SoftShadows patches WebGL shader code. Verify it against the installed Three.js shadow implementation before adding it, especially after a renderer upgrade.
- Keep tone mapping/exposure consistent while tuning lights. Current physically based light intensities should not be mixed blindly with old legacy-light tutorials.
Verify
Check shadow contact, acne, clipping, loaded-model cast/receive flags, and moving objects. Compare static versus animated capture behavior and measure total render passes on the target device.
Sources
1---
2name: r3f-lighting
3description: Light React Three Fiber scenes with direct lights, environment maps, and shadows. Use for light placement, image-based lighting, shadow artifacts, and lighting performance.
4metadata:
5 source: https://skillmd.com/skills/enzed/r3f-lighting
6---
7
8# React Three Fiber lighting
9
10Check installed Three.js, Fiber, and Drei versions and the renderer first. This example targets Fiber 9 / React 19, Three.js r185, and WebGL.
11
12## Start with a deliberate lighting setup
13
14- Use environment lighting for PBR reflections/fill and direct lights for direction and real-time shadowing. More ambient light will not restore missing metallic reflections.
15- A scene background and `scene.environment` serve different purposes. Drei `Environment` assigns lighting; `background` additionally makes it visible behind the scene.
16- Prefer an owned HDR/EXR asset in production. Drei presets are useful for prototyping but depend on external hosting. Check loader support before choosing newer formats.
17- `Sky` is visible sky geometry, not automatically a matching sun light or environment. Align the sky, direct light, and environment when visual consistency matters.
18
19## Shadowed scene
20
21Mount inside `<Canvas shadows="percentage">`. On Three.js r182+, PCFShadowMap is soft; Fiber 9's bare `shadows` selects the deprecated PCFSoftShadowMap.
22
23```tsx
24export default function Example() {
25 return (
26 <>
27 <ambientLight intensity={0.3} />
28 <directionalLight
29 position={[3, 5, 3]}
30 intensity={3}
31 castShadow
32 shadow-mapSize={[1024, 1024]}
33 shadow-camera-left={-4}
34 shadow-camera-right={4}
35 shadow-camera-top={4}
36 shadow-camera-bottom={-4}
37 shadow-camera-near={0.5}
38 shadow-camera-far={15}
39 shadow-normalBias={0.02}
40 />
41 <mesh castShadow position={[0, 0.5, 0]}>
42 <boxGeometry />
43 <meshStandardMaterial color="coral" />
44 </mesh>
45 <mesh receiveShadow rotation={[-Math.PI / 2, 0, 0]}>
46 <planeGeometry args={[8, 8]} />
47 <meshStandardMaterial color="silver" />
48 </mesh>
49 </>
50 )
51}
52```
53
54Bias and frustum values above are for this small scene; retune them for actual dimensions.
55
56## Shadows and light targets
57
58- Shadow mapping needs renderer shadows enabled, a shadow-casting light, casting meshes, and receiving materials/meshes. Ambient and hemisphere lights do not cast shadows.
59- Tighten the shadow camera to the useful region before increasing map resolution. Inspect its frustum with a CameraHelper; bias should address acne without detaching shadows from objects.
60- Point-light shadows render six directions. Limit shadow-casting lights and large maps; cost depends on affected geometry and passes, not just light count.
61- Moving a directional/spot light's target requires a target Object3D whose world matrix updates. Add a custom target to the scene graph; changing only a detached target's position can leave its world transform stale.
62- With WebGL, RectAreaLight affects Standard/Physical materials and does not cast built-in shadows. Initialize `RectAreaLightUniformsLib` when using the native light path that requires it.
63- Object/camera layers are not general per-light material masks in WebGLRenderer. Do not promise that matching a light layer to a mesh makes selective illumination work.
64
65## Environment and helper cost
66
67- Drei `Lightformer` is emissive geometry captured into an Environment; it is not an ordinary real-time light and does not cast direct-light shadows.
68- Set `frames={1}` for genuinely static environment captures or ContactShadows. Animated objects/lighting need recapture; a frozen capture will remain stale.
69- ContactShadows renders an offscreen depth/blur approximation. It is not free and does not replace all directional shadows.
70- AccumulativeShadows converges across samples; changing the scene can require reset/reaccumulation. BakeShadows freezes updates rather than producing a portable baked lightmap.
71- SoftShadows patches WebGL shader code. Verify it against the installed Three.js shadow implementation before adding it, especially after a renderer upgrade.
72- Keep tone mapping/exposure consistent while tuning lights. Current physically based light intensities should not be mixed blindly with old legacy-light tutorials.
73
74## Verify
75
76Check shadow contact, acne, clipping, loaded-model cast/receive flags, and moving objects. Compare static versus animated capture behavior and measure total render passes on the target device.
77
78## Sources
79
80- [Drei Environment](https://drei.docs.pmnd.rs/staging/environment), [ContactShadows](https://drei.docs.pmnd.rs/staging/contact-shadows).
81- [Three.js shadows](https://threejs.org/manual/en/shadows.html), [RectAreaLight](https://threejs.org/docs/#RectAreaLight), [DirectionalLight](https://threejs.org/docs/#DirectionalLight).
82- [Migration guide](https://github.com/mrdoob/three.js/wiki/Migration-Guide) — PCF changes in r182 and environment rotation changes in r184.