/web-3d-react-three-fiber

name: web-3d-react-three-fiber
description: React Three Fiber (R3F) 3D rendering — Canvas, meshes, materials, lights, cameras, animations, events, physics, post-processing, performance

React Three Fiber Patterns

> **Quick Guide:** R3F is a React reconciler for Three.js, so the React tree is the scene graph and every Three.js class is a camelCase JSX element — `<mesh>`, `<boxGeometry>`, `<meshStandardMaterial>`. `<Canvas>` creates the renderer, scene and camera, and every R3F hook must be called inside it. Per-frame work goes through `useFrame` mutating refs, never through state; structural changes go through state as usual. Assets load through `useLoader`/`useGLTF`, which suspend, so their components need a `<Suspense>` boundary. Pointer events raycast into the scene and reach occluded objects unless `stopPropagation()` is called.

> **Import:** `import { Canvas, useFrame, useThree, useLoader } from "@react-three/fiber"`

**Detailed Resources:**

• [examples/core.md](examples/core.md) — Canvas setup, lighting rigs, `useFrame` animation, asset loading, drei helpers, physics
• [examples/interaction.md](examples/interaction.md) — the event object, propagation, hover, click-versus-drag, pointer capture, the full event list
• [examples/performance.md](examples/performance.md) — instancing, LOD, on-demand rendering, resource sharing, disposal, adaptive quality
• [reference.md](reference.md) — Canvas props, hook signatures, the event type, ecosystem packages, Three.js-to-JSX mapping, collider types

---

<critical_requirements>

Before writing React Three Fiber code

**Do per-frame work by mutating refs inside `useFrame`, and allocate the objects it needs outside it.** State in the frame loop re-renders React sixty times a second, and `new THREE.Vector3()` inside it allocates sixty objects a second for the garbage collector to reclaim.

**Multiply per-frame motion by `delta`.** The callback's second argument is seconds since the last frame, which is what makes a rotation the same speed on a 60Hz and a 144Hz display.

**Put a `<Suspense>` boundary above anything calling `useLoader` or `useGLTF`.** Those hooks suspend while the asset downloads, and a suspending component with no boundary above it takes the tree down.

**Share geometries and materials across meshes that use the same ones.** They are GPU allocations, and R3F does not deduplicate declarative children — twenty-five `<sphereGeometry>` elements are twenty-five uploads.

**Call `event.stopPropagation()` in pointer handlers.** A raycast returns every intersection along the ray, so without it a click reaches the objects behind the one that was clicked.

</critical_requirements>

---

**Auto-detection:** @react-three/fiber, @react-three/drei, @react-three/rapier, @react-three/postprocessing, R3F, Canvas, useFrame, useThree, useLoader, useGLTF, useGraph, invalidate, frameloop, instancedMesh, boxGeometry, meshStandardMaterial, OrbitControls, Environment, Detailed, RigidBody, CuboidCollider, EffectComposer, onPointerMissed, three

**Applies to:**

• 3D scenes, product viewers, visualizations and interactive experiences in React
• Loading and displaying models (GLTF, Draco-compressed GLTF, textures)
• Per-frame animation, and interaction-driven state changes
• Pointer events, raycasting and drag on 3D objects
• Physics simulation, colliders, and collision or trigger events
• Post-processing effect chains
• Scaling a scene: instancing, level of detail, on-demand rendering, adaptive quality

**Handled elsewhere:**

• 2D interface work — HTML overlays anchored to a 3D position are this skill's `Html` helper, but the markup inside them is ordinary UI
• Pre-rendering a 3D scene to a static image at build time
• Which colours, fonts and materials a product uses — every one of these components takes them as props
• Accessibility conformance targets — a canvas is one element to assistive technology, so a scene's controls need an accessible equivalent, and what that must satisfy is settled elsewhere

---

<philosophy>

**The React tree is the scene graph.** Mounting a component adds a mesh; unmounting removes and disposes it. Suspense, context and refs all work in 3D exactly as they do in the DOM, because there is one reconciler doing both.

The split that matters is **refs for mutation, state for structure**. Position, rotation and scale change every frame and belong to refs, where React never sees them. Which objects exist, and whether one is selected, are structure and belong to state. Getting this backwards — animating through state — is the single most common way an R3F scene becomes slow, and it looks correct until the frame counter is opened.

</philosophy>

---

<decision_framework>

How to animate

Continuous per-frame motion (spin, bob, orbit)
  -> useFrame mutating a ref; multiply by delta
Discrete change from an interaction (hover colour, selected scale)
  -> React state; it happens once, not per frame
One-time entrance
  -> useFrame with a progress ref clamped at 1, or a spring-based
     animation approach driving the same refs

Which collider

Box            -> "cuboid"   fastest
Sphere         -> "ball"     fast
Convex shape   -> "hull"     good balance
Concave shape  -> "trimesh"  expensive; use sparingly

How to scale a scene

Many identical objects        -> instancedMesh, or drei's <Instances>
Many different static meshes  -> merge their geometries into one mesh
Objects seen at varying range -> LOD via <Detailed>
Mostly static scene           -> frameloop="demand" plus invalidate()
Frame rate varies by device   -> PerformanceMonitor driving dpr
Otherwise                     -> count draw calls; each <mesh> is one

</decision_framework>

---

<patterns>

Core patterns

Pattern 1: Canvas and scene setup

`<Canvas>` builds the renderer, scene and camera, and establishes the context every R3F hook reads.

<Canvas
  camera={{ fov: CAMERA_FOV, position: CAMERA_POSITION, near: 0