Declarative 3D scenes in React. Complements the skill threejs (imperative vanilla Three.js).
Mental Model
React and Three.js handle distinct domains that communicate via refs:
- React owns the scene graph: mounts, unmounts, reconciles JSX components → Three.js objects
- Three.js owns the render loop:
useFrameruns every frame, mutates refs directly - Golden rule: React for state and structure, refs for per-frame mutations
React tree (JSX, state, props)
↕ refs / props
useFrame callbacks (per-frame mutations)
↕ escribe en Three.js objects
WebGLRenderer (render en priority 0)
When to Use This Skill vs threejs
| Scenario | Skill |
|---|---|
| React + JSX project for 3D | r3f (this one) |
| Imperative vanilla Three.js | threejs |
| Concepts of materials, lights, shadows | threejs (apply the same) |
| Hooks: useFrame, useThree, useLoader | r3f |
| drei helpers: controls, staging, text | r3f |
| CSG with @react-three/csg | r3f |
Quick Start
import { Canvas } from '@react-three/fiber'
import { OrbitControls, Environment } from '@react-three/drei'
function Box() {
return (
<mesh castShadow>
<boxGeometry args={[1, 1, 1]} />
<meshStandardMaterial color="orange" roughness={0.4} />
</mesh>
)
}
export function Scene() {
return (
<Canvas shadows camera={{ position: [3, 3, 3], fov: 50 }}>
<ambientLight intensity={0.4} />
<directionalLight position={[5, 5, 5]} castShadow />
<Box />
<OrbitControls makeDefault />
<Environment preset="studio" />
</Canvas>
)
}
Learning Path
Level 1: Core R3F
- Canvas and Hooks:
references/01-canvas-hooks.md— Canvas props, useThree, useFrame, useLoader, useGraph - JSX and Events:
references/02-jsx-system.md— JSX→Three.js mapping, args, attach, extend, primitive, events
Level 2: drei Ecosystem
- Controls:
references/03-drei-controls.md— OrbitControls, CameraControls, PivotControls, TransformControls, Keyboard/Scroll - Staging:
references/04-drei-staging.md— Environment, shadows, Sky, special materials - Abstractions:
references/05-drei-abstractions.md— Text, Html, Billboard, Image, Clone, loaders, animations
Level 3: Performance and Patterns
- Performance:
references/06-drei-performance.md— Bvh, Instances, LOD, PerformanceMonitor, dispose, FBO - Zustand Bridge:
references/07-zustand-integration.md— getState() in useFrame, invalidate(), demand rendering
Level 4: Specialized
- CSG Operations:
references/08-csg-operations.md— @react-three/csg, three-bvh-csg, boolean geometry - TypeScript v9:
references/09-typescript-v9.md— ThreeElements, ThreeElement, module augmentation, migration - Patterns and Gotchas:
references/10-patterns-gotchas.md— anti-patterns, disposal, Suspense, portals
10 Core Rules
- Never setState in useFrame — causes re-render at 60fps. Use refs or
useStore.getState() - useThree with selector —
useThree(s => s.camera), notuseThree()bare (re-render on every state change) - extend() mandatory for custom objects — v9 does not auto-discover.
extend({ MyClass })before the JSX - Suspense boundary around loaders —
useGLTF,useTexture,useLoadersuspend the component - frameloop="demand" for static scenes —
invalidate()from useThree or store to trigger frames - args as constant —
args={[1,1,1]}inline recreates every render. Hoist oruseMemo - dispose={null} for shared resources — R3F auto-disposes on unmount; prevent with
dispose={null} - makeDefault on controls — registers in
state.controlsso drei components can access it - primitive does not clone —
<primitive object={obj}/>uses the same reference. Use<Clone>from drei to reuse - Events only on meshes with geometry —
onClickin<group>without geometry does not fire
Anti-Patterns
| Anti-pattern | Problem | Fix |
|---|---|---|
setState(x) in useFrame |
Re-renders 60fps | Refs or Zustand getState() |
useThree() without selector |
Re-render on any change | useThree(s => s.camera) |
new THREE.Vector3() in render |
GC pressure per-frame | Hoist or useMemo |
args={[w,h,d]} inline |
Rebuilds geometry every render | useMemo(() => [w,h,d], [w,h,d]) |
1000 <mesh> individual |
Slow reconciliation | <Instances> from drei |
useEffect to animate |
Outside the render loop | useFrame with refs |
Pre-Deploy Checklist
[ ] frameloop="demand" si la escena no se anima constantemente
[ ] <Suspense> alrededor de componentes con loaders
[ ] dispose={null} en <primitive> de recursos compartidos
[ ] <Bvh> wrapper si hay muchos meshes clickeables
[ ] dpr={[1, 2]} en Canvas para DPR adaptativo
[ ] OrbitControls con makeDefault
[ ] Sin setState en ningun useFrame
[ ] gl={{ preserveDrawingBuffer: true }} solo si necesitas screenshots
Resources
- R3F Docs: https://r3f.docs.pmnd.rs/
- drei Docs: https://drei.docs.pmnd.rs/
- drei GitHub: https://github.com/pmndrs/drei
- R3F GitHub: https://github.com/pmndrs/react-three-fiber
- three-bvh-csg: https://github.com/gkjohnson/three-bvh-csg