React Three Fiber fundamentals
Choose the right baseline
- Inspect the project's manifest and lockfile before selecting APIs. These examples target Fiber 9 / React 19; Fiber 8 pairs with React 18. Do not upgrade a project just to match a recipe.
- Check installed Three.js and Drei versions too. Use released documentation matching those versions; if unavailable, state the uncertainty instead of inventing props.
- Keep the existing renderer unless the task calls for changing it. For WebGPU, read renderer selection; Fiber 10 alpha APIs are not Fiber 9 APIs.
Minimal scene
This example owns its Canvas. Its parent must have a nonzero height.
import { useRef } from 'react'
import { Canvas, useFrame, type ThreeElements } from '@react-three/fiber'
import type { Mesh } from 'three'
function RotatingBox(props: ThreeElements['mesh']) {
const mesh = useRef<Mesh>(null)
useFrame((_, delta) => {
if (mesh.current) mesh.current.rotation.y += delta * 0.5
})
return (
<mesh {...props} ref={mesh}>
<boxGeometry args={[1, 1, 1]} />
<meshStandardMaterial color="coral" />
</mesh>
)
}
export default function Example() {
return (
<Canvas camera={{ position: [0, 0, 5] }} dpr={[1, 2]}>
<ambientLight intensity={0.5} />
<directionalLight position={[3, 4, 5]} intensity={2} />
<RotatingBox />
</Canvas>
)
}
Scene and type boundaries
- Call
useThree, useFrame, and loader hooks in components beneath Canvas, never in the component creating that Canvas or inside an event callback.
- Canvas children are Three.js objects. Place DOM UI outside it or use Drei
Html. A Suspense fallback inside Canvas must obey the same rule.
- Use
ThreeElements['mesh'] for mesh props and useRef<Mesh>(null) for refs. Fiber 9 uses ThreeElement<typeof Class> for custom elements; do not use removed Object3DNode or global JSX.IntrinsicElements augmentation.
extend(Class) creates a locally typed component in Fiber 9. Use extend({ Class }) plus module augmentation of @react-three/fiber when a shared lowercase JSX element is actually needed.
args are constructor arguments: changing them reconstructs the object. Update ordinary props or refs for animation; retain expensive shapes, arrays, and materials when their inputs have not changed.
- Geometry/material children attach automatically. Use explicit
attach for other properties, e.g. attach="attributes-position" for a buffer attribute.
- Three.js uses radians and local transforms. Convert world-space input into the object's parent space before assigning it to
position.
Render-loop decisions
- Use React state for discrete UI changes; mutate owned refs for per-frame motion. Reuse scratch vectors and use
delta in seconds. Do not create a second animation loop for the same scene.
useThree(state => state.camera) subscribes to camera replacement, not mutations of camera.position. Read transient values inside useFrame; update the projection matrix after imperative camera projection changes.
- Default
frameloop="always" fits continuous animation. Use "demand" for scenes that can rest: imperative changes need invalidate(), and animations must keep invalidating until settled. Drei controls handle their own invalidation.
- Negative frame priorities order updates without taking over rendering. A positive priority disables automatic rendering: its owner must render, and must coordinate with any composer. Callbacks run in ascending priority order.
- Do not reset transforms in JSX and animate the same values from another owner. Visibility changes do not automatically stop callbacks or release GPU resources.
Renderer and ownership pitfalls
- Default WebGL Canvas uses sRGB output and ACES filmic tone mapping.
flat selects NoToneMapping; linear changes output color space. Neither is a generic fix for washed-out assets.
- On Three.js r182+, use
shadows="percentage" for PCF shadows. Bare shadows in Fiber 9 selects deprecated PCFSoftShadowMap on this baseline.
- Start with defaults; add
preserveDrawingBuffer, larger DPR, or extra render passes only for an actual requirement and measure their cost.
- R3F disposes declaratively owned objects when unmounted.
<primitive object={...}> does not dispose the supplied object. Cached loader assets and shared resources need an explicit owner; do not dispose them while another consumer uses them.
dispose={null} opts a subtree out of automatic disposal; it is not a general performance switch. Manually allocated resources outside R3F's ownership need cleanup.
- Effects, subscriptions, and imperative registrations must survive Strict Mode setup/cleanup. Profile before adding memoization; ordinary React renders do not inherently restart
useFrame animation.
Verify
Type-check, render in a browser, check the console, resize, and unmount/remount. For demand rendering, verify both waking and returning to idle.
Sources
1---
2name: r3f-fundamentals
3description: Set up React Three Fiber scenes, Canvas, typed JSX, hooks, and resource ownership. Use for scene architecture and render-loop setup, rather than detailed materials or effects.
4metadata:
5 source: https://skillmd.com/skills/enzed/r3f-fundamentals
6---
7
8# React Three Fiber fundamentals
9
10## Choose the right baseline
11
12- Inspect the project's manifest and lockfile before selecting APIs. These examples target Fiber 9 / React 19; Fiber 8 pairs with React 18. Do not upgrade a project just to match a recipe.
13- Check installed Three.js and Drei versions too. Use released documentation matching those versions; if unavailable, state the uncertainty instead of inventing props.
14- Keep the existing renderer unless the task calls for changing it. For WebGPU, read [renderer selection](references/renderers.md); Fiber 10 alpha APIs are not Fiber 9 APIs.
15
16## Minimal scene
17
18This example owns its Canvas. Its parent must have a nonzero height.
19
20```tsx
21import { useRef } from 'react'
22import { Canvas, useFrame, type ThreeElements } from '@react-three/fiber'
23import type { Mesh } from 'three'
24
25function RotatingBox(props: ThreeElements['mesh']) {
26 const mesh = useRef<Mesh>(null)
27 useFrame((_, delta) => {
28 if (mesh.current) mesh.current.rotation.y += delta * 0.5
29 })
30 return (
31 <mesh {...props} ref={mesh}>
32 <boxGeometry args={[1, 1, 1]} />
33 <meshStandardMaterial color="coral" />
34 </mesh>
35 )
36}
37
38export default function Example() {
39 return (
40 <Canvas camera={{ position: [0, 0, 5] }} dpr={[1, 2]}>
41 <ambientLight intensity={0.5} />
42 <directionalLight position={[3, 4, 5]} intensity={2} />
43 <RotatingBox />
44 </Canvas>
45 )
46}
47```
48
49## Scene and type boundaries
50
51- Call `useThree`, `useFrame`, and loader hooks in components beneath Canvas, never in the component creating that Canvas or inside an event callback.
52- Canvas children are Three.js objects. Place DOM UI outside it or use Drei `Html`. A Suspense fallback inside Canvas must obey the same rule.
53- Use `ThreeElements['mesh']` for mesh props and `useRef<Mesh>(null)` for refs. Fiber 9 uses `ThreeElement<typeof Class>` for custom elements; do not use removed `Object3DNode` or global `JSX.IntrinsicElements` augmentation.
54- `extend(Class)` creates a locally typed component in Fiber 9. Use `extend({ Class })` plus module augmentation of `@react-three/fiber` when a shared lowercase JSX element is actually needed.
55- `args` are constructor arguments: changing them reconstructs the object. Update ordinary props or refs for animation; retain expensive shapes, arrays, and materials when their inputs have not changed.
56- Geometry/material children attach automatically. Use explicit `attach` for other properties, e.g. `attach="attributes-position"` for a buffer attribute.
57- Three.js uses radians and local transforms. Convert world-space input into the object's parent space before assigning it to `position`.
58
59## Render-loop decisions
60
61- Use React state for discrete UI changes; mutate owned refs for per-frame motion. Reuse scratch vectors and use `delta` in seconds. Do not create a second animation loop for the same scene.
62- `useThree(state => state.camera)` subscribes to camera replacement, not mutations of `camera.position`. Read transient values inside `useFrame`; update the projection matrix after imperative camera projection changes.
63- Default `frameloop="always"` fits continuous animation. Use `"demand"` for scenes that can rest: imperative changes need `invalidate()`, and animations must keep invalidating until settled. Drei controls handle their own invalidation.
64- Negative frame priorities order updates without taking over rendering. A positive priority disables automatic rendering: its owner must render, and must coordinate with any composer. Callbacks run in ascending priority order.
65- Do not reset transforms in JSX and animate the same values from another owner. Visibility changes do not automatically stop callbacks or release GPU resources.
66
67## Renderer and ownership pitfalls
68
69- Default WebGL Canvas uses sRGB output and ACES filmic tone mapping. `flat` selects `NoToneMapping`; `linear` changes output color space. Neither is a generic fix for washed-out assets.
70- On Three.js r182+, use `shadows="percentage"` for PCF shadows. Bare `shadows` in Fiber 9 selects deprecated `PCFSoftShadowMap` on this baseline.
71- Start with defaults; add `preserveDrawingBuffer`, larger DPR, or extra render passes only for an actual requirement and measure their cost.
72- R3F disposes declaratively owned objects when unmounted. `<primitive object={...}>` does not dispose the supplied object. Cached loader assets and shared resources need an explicit owner; do not dispose them while another consumer uses them.
73- `dispose={null}` opts a subtree out of automatic disposal; it is not a general performance switch. Manually allocated resources outside R3F's ownership need cleanup.
74- Effects, subscriptions, and imperative registrations must survive Strict Mode setup/cleanup. Profile before adding memoization; ordinary React renders do not inherently restart `useFrame` animation.
75
76## Verify
77
78Type-check, render in a browser, check the console, resize, and unmount/remount. For demand rendering, verify both waking and returning to idle.
79
80## Sources
81
82- [Fiber 9 migration](https://github.com/pmndrs/react-three-fiber/blob/v9.7.0/docs/tutorials/v9-migration-guide.mdx) — version-sensitive types and renderer setup.
83- [Canvas](https://r3f.docs.pmnd.rs/api/canvas), [objects and disposal](https://r3f.docs.pmnd.rs/api/objects), [hooks](https://r3f.docs.pmnd.rs/api/hooks).
84- [Performance pitfalls](https://r3f.docs.pmnd.rs/advanced/pitfalls), [on-demand rendering](https://r3f.docs.pmnd.rs/advanced/scaling-performance).