/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 renderer for Three.js. Every Three.js class maps to a JSX element (`<mesh>`, `<boxGeometry>`, `<meshStandardMaterial>`). Use `<Canvas>` for scene setup, `useFrame` for per-frame logic (never setState inside it), `useRef` for direct mutations, and `useLoader`/`useGLTF` for assets. Animate via refs in `useFrame`, not React state. Events work like DOM events with raycasting built in. Wrap exiting 3D components in `<Suspense>` for async asset loading.

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

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST never call setState inside useFrame -- mutate refs directly for per-frame updates)**

**(You MUST wrap `<Canvas>` children that load assets in `<Suspense>` boundaries)**

**(You MUST reuse geometries and materials across meshes -- creating new instances per mesh wastes GPU memory)**

**(You MUST call `event.stopPropagation()` on pointer events to prevent hits passing through to occluded objects)**

**(You MUST use named constants for all numeric values -- positions, sizes, speeds, colors -- NO magic numbers)**

</critical_requirements>

---

**Auto-detection:** React Three Fiber, R3F, @react-three/fiber, @react-three/drei, @react-three/rapier, @react-three/postprocessing, Canvas, useFrame, useThree, useLoader, useGLTF, mesh, boxGeometry, meshStandardMaterial, OrbitControls, drei, three.js, 3D scene, WebGL, instancedMesh

**When to use:**

• Building 3D scenes, visualizations, or experiences in React
• Loading and displaying 3D models (GLTF, OBJ, FBX)
• Adding physics simulation to 3D objects
• Handling pointer/click interactions on 3D meshes
• Animating objects per-frame (rotation, position, scale)
• Applying post-processing effects (bloom, depth of field, SSAO)

**When NOT to use:**

• 2D-only UIs (standard React components)
• Static images of 3D content (pre-render instead)
• Performance-critical scenarios where raw Three.js without React overhead is needed

**Key patterns covered:**

• Canvas setup with camera, shadows, and renderer config
• Declarative meshes, geometries, materials, and lights
• Per-frame animation with `useFrame` and refs
• Pointer events, raycasting, and event propagation
• Asset loading with `useLoader`, `useGLTF`, and Suspense
• Drei helpers (OrbitControls, Environment, Text, Html, Detailed)
• Physics with `@react-three/rapier` (RigidBody, colliders, collision events)
• Post-processing with `@react-three/postprocessing`
• Performance: instancing, LOD, on-demand rendering, geometry reuse, disposal

---

**Detailed Resources:**

• [examples/core.md](examples/core.md) - Canvas, meshes, materials, lights, camera, useFrame, asset loading, drei helpers
• [examples/interaction.md](examples/interaction.md) - Events, raycasting, hover/click, drag, pointer capture
• [examples/performance.md](examples/performance.md) - Instancing, LOD, disposal, frame loop control, on-demand rendering
• [reference.md](reference.md) - Decision frameworks, Canvas props, hook signatures, anti-patterns

---

<philosophy>

Philosophy

React Three Fiber is a React reconciler for Three.js -- every Three.js object becomes a declarative JSX element. The React tree IS the scene graph. Components mount/unmount meshes, lights, and cameras just like DOM elements. This means React features (Suspense, context, refs, state) all work naturally in 3D.

**Core principles:**

1. **Declarative scene graph** -- describe WHAT the scene looks like, not HOW to build it imperatively 2. **Refs for mutations, state for structure** -- per-frame updates go through `useRef` in `useFrame`, structural changes (adding/removing objects) go through React state 3. **Reuse everything** -- geometries, materials, and textures are GPU resources; share them across meshes 4. **Suspense for async** -- wrap asset-loading components in `<Suspense>` for automatic loading states 5. **Events are raycasted** -- pointer events automatically raycast into the scene; `stopPropagation` prevents hits on occluded objects

**The R3F ecosystem:**

| Package | Purpose | |---------|---------| | `@react-three/fiber` | Core renderer -- Canvas, hooks, reconciler | | `@react-three/drei` | Helpers -- controls, loaders, abstractions, text, HTML overlays | | `@react-three/rapier` | Physics -- rigid bodies, colliders, collision events | | `@react-three/postprocessing` | Effects -- bloom, DOF, SSAO, vignette |

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Canvas and Scene Setup

`<Canvas>` creates a WebGL context with scene, camera, and renderer. All R3F hooks must be used inside Canvas.

import { Canvas } from "@react-three/fiber";

const CAMERA_FOV = 50;
const CAMERA_POSITION: [number, number, number] = [0, 2, 5];

export function Scene() {
  return (
    <Canvas
      camera={{ fov: CAMERA_FOV, position: CAMERA_POSITION, near: 0.1, far: 100 }}
      shadows
      dpr={[1, 2]}
      frameloop="always"
    >
      <ambientLight intensity={0.5} />
      <directionalLight position={[5, 5, 5]} castShadow />
      <mesh castShadow receiveShadow>
        <boxGeometry args={[1, 1, 1]} />
        <meshStandardMaterial color="orange" />
      </mesh>
    </Canvas>
  );
}

**Why good:** named position constant, shadows enabled on canvas + individual meshes, dpr clamped to prevent excessive resolution on HiDPI displays

See [examples/core.md](examples/core.md) Pattern 1 for full Canvas config, lighting setups, and camera types.

---

Pattern 2: Per-Frame Animation with useFrame

`useFrame` runs every frame before render. Mutate r