threejs-impl-react-three-fiber
/threejs-impl-react-three-fiber
Use when building 3D scenes with React using React Three Fiber (R3F). Prevents the common mistake of mixing imperative Three.js code with R3F's declarative model, creating objects inside useFrame, or forgetting Suspense for loaders. Covers Canvas, useFrame, useThree, useLoader, JSX mapping, event system, performance patterns. Keywords: React Three Fiber, R3F, Canvas, useFrame, useThree, useLoader, @react-three/fiber, 3D React, declarative Three.js, use Three.js with React, JSX 3D components.
- Author
- Qadri-uk ↗
- Repository
- claude-skills ↗
- Licence
- MIT
- Last repository change
- 09.11.2026
Assessment and security
- Files in this package
- 5
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 4
No signals detected. Repository changed on 09.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Use when building 3D scenes with React using React Three Fiber (R3F). Prevents the common mistake of mixing imperative Three.js code with R3F's declarative model, creating objects inside useFrame, or forgetting Suspense for loaders. Covers Canvas, useFrame, useThree, useLoader, JSX mapping, event system, performance patterns. Keywords: React Three Fiber, R3F, Canvas, useFrame, useThree, useLoader, @react-three/fiber, 3D React, declarative Three.js, use Three.js with React, JSX 3D components.
Original author description
Use when building 3D scenes with React using React Three Fiber (R3F). Prevents the common mistake of mixing imperative Three.js code with R3F's declarative model, creating objects inside useFrame, or forgetting Suspense for loaders. Covers Canvas, useFrame, useThree, useLoader, JSX mapping, event system, performance patterns. Keywords: React Three Fiber, R3F, Canvas, useFrame, useThree, useLoader, @react-three/fiber, 3D React, declarative Three.js, use Three.js with React, JSX 3D components.
How it works
- Quick Reference
- JSX-to-Three.js Mapping Rules
- Hooks
- Primitives and extend()
- Event System
- Performance Patterns
- Reference Links
SKILL.md preview
---
name: threejs-impl-react-three-fiber
description: >
Use when building 3D scenes with React using React Three Fiber (R3F).
Prevents the common mistake of mixing imperative Three.js code with
R3F's declarative model, creating objects inside useFrame, or
forgetting Suspense for loaders. Covers Canvas, useFrame, useThree,
useLoader, JSX mapping, event system, performance patterns.
Keywords: React Three Fiber, R3F, Canvas, useFrame, useThree, useLoader, @react-three/fiber, 3D React, declarative Three.js, use Three.js with React, JSX 3D components.
license: MIT
compatibility: "Designed for Claude Code. Requires @react-three/fiber 8.x+, React 18+."
metadata:
author: OpenAEC-Foundation
version: "1.0"
---
# threejs-impl-react-three-fiber
## Quick Reference
### Canvas Component Props
| Prop | Type | Default | Purpose |
|------|------|---------|---------|
| `gl` | `Renderer props \| (canvas) => Renderer` | `{}` | WebGL renderer config or factory |
| `camera` | `Camera props \| THREE.Camera` | `{ fov: 75, near: 0.1, far: 1000, position: [0,0,5] }` | Default camera |
| `scene` | `Scene props \| THREE.Scene` | `{}` | Scene configuration |
| `shadows` | `boolean \| ShadowMapType` | `false` | Enable shadow maps |
| `raycaster` | `Raycaster props` | `{}` | Raycaster configuration |
| `frameloop` | `"always" \| "demand" \| "never"` | `"always"` | Render loop strategy |
| `resize` | `ResizeOptions` | `{ scroll: true, debounce: { scroll: 50, resize: 0 } }` | Resize behavior |
| `orthographic` | `boolean` | `false` | Use OrthographicCamera |
| `dpr` | `number \| [min, max]` | `[1, 2]` | Device pixel ratio |
| `linear` | `boolean` | `false` | Linear color space |
| `flat` | `boolean` | `false` | Disable tone mapping |
| `legacy` | `boolean` | `false` | Disable color management |
| `events` | `EventManager` | R3F default | Custom event manager |
| `eventSource` | `HTMLElement \| React.RefObject` | Parent node | Event capture element |
| `eventPrefix` | `string` | `"offset"` | Coordinate prefix |
| `onCreated` | `(state: RootState) => void` | -- | Post-init callback |
| `onPointerMissed` | `(event: PointerEvent) => void` | -- | Click misses all meshes |
| `fallback` | `React.ReactNode` | -- | DOM fallback during init |
### Frameloop Modes
| Mode | Behavior |
|------|----------|
| `"always"` | ALWAYS renders every frame via requestAnimationFrame |
| `"demand"` | ONLY renders when `invalidate()` is called -- use for static scenes |
| `"never"` | NEVER renders automatically -- caller MUST invoke `advance(timestamp)` |
### Critical Warnings
**NEVER** create Three.js objects inside `useFrame` -- this allocates memory every frame and causes GC pressure. ALWAYS create objects outside the callback or use `useMemo`.
**NEVER** forget `<Suspense>` when using `useLoader` -- the component WILL suspend and crash without a Suspense boundary.
**NEVER** add the same Three.js object instance to the scene tree multiple times via `<primitive>` -- Three.js objects can only have one parent.
**NEVER** use `useThree()` without a selector when you only need one property -- the full state object triggers re-renders on every frame. ALWAYS use `useThree((s) => s.camera)`.
**NEVER** mix imperative `scene.add()` calls with R3F's declarative JSX tree -- R3F manages the scene graph and imperative mutations cause desync.
**ALWAYS** use `delta` from `useFrame` for animations -- hardcoded time steps cause speed variations across different frame rates.
**ALWAYS** use `useMemo` for imperatively created geometries and materials -- without it, new objects are allocated on every render.
---
## JSX-to-Three.js Mapping Rules
R3F uses deterministic conventions to translate JSX into Three.js scene graph operations:
1. **Lowercase JSX = Three.js class.** `<mesh />` creates `new THREE.Mesh()`. `<meshStandardMaterial />` creates `new THREE.MeshStandardMaterial()`.
2. **`args` = constructor arguments (array).** `<sphereGeometry args={[1, 32, 32]} />` becomes `new THREE.SphereGeometry(1, 32, 32)`. When `args` changes, the object is destroyed and recreated.
3. **`attach` = parent property binding.** `<meshStandardMaterial attach="material" />` sets `parent.material = this`. Geometries auto-attach to `"geometry"`, materials to `"material"`.
4. **Dash-notation attach for nested paths.** `attach="shadow-camera"` sets `parent.shadow.camera = this`. Array indexing: `attach="material-0"`.
5. **Functional attach.** `attach={(parent, self) => { parent.add(self); return () => parent.remove(self); }}` for custom bind/unbind.
6. **Properties with `.set()` accept shorthand.** `position={[1, 2, 3]}` calls `object.position.set(1, 2, 3)`. `color="hotpink"` calls `object.color.set("hotpink")`.
7. **Scalar shorthand.** `scale={2}` calls `object.scale.setScalar(2)`.
8. **Dash-case pierces nested properties.** `rotation-x={Math.PI}` sets `object.rotation.x = Math.PI`.
---
## Hooks
### useFrame
```typescript
useFrame((state: RootState, delta: number, xrFrame?: XRFrame) => void, priority?: number)
```
Subscribes a callback to the render loop. Executes every frame.
**State object key properties:**
| Property | Type | Description |
|----------|------|-------------|
| `gl` | `THREE.WebGLRenderer` | The renderer |
| `scene` | `THREE.Scene` | The scene |
| `camera` | `THREE.Camera` | Active camera |
| `clock` | `THREE.Clock` | System clock |
| `pointer` | `THREE.Vector2` | Normalized pointer (-1 to +1) |
| `size` | `{ width, height, top, left }` | Canvas dimensions (px) |
| `viewport` | `{ width, height, factor, distance, aspect }` | Camera-relative metrics |
| `invalidate` | `() => void` | Request render in demand mode |
| `advance` | `(timestamp: number) => void` | Advance one tick in never mode |
| `performance` | `{ current, min, max, regress() }` | Adaptive performance |
| `set` | `(state) => void` | Mutate state directly |
| `get` | `() => RootState` | Read state non-reactively |
**Priority system:** Callbacks execute in ascending priority order. When ANY callback has priority > 0, R3F disables automatic `renderer.render()`. The highest-priority subscriber MUST call `state.gl.render(state.scene, state.camera)` manually. Negative priorities do NOT disable auto-rendering.
### useThree
```typescript
const state = useThree() // full state (re-renders often)
const camera = useThree((state) => state.camera) // selector (re-renders only on change)
```
Returns the RootState (same object as useFrame's state). ALWAYS use a selector when only one property is needed.
### useLoader
```typescript
const result = useLoader(LoaderClass, url, extensions?, onProgress?)
const results = useLoader(LoaderClass, [url1, url2], extensions?)
```
Suspense-based asset loading. ALWAYS wrap in `<Suspense fallback={...}>`.
- Assets are cached by URL -- loading the same URL twice returns the cached result.
- `useLoader.preload(LoaderClass, url)` preloads before component mount.
- GLTF results include `{ nodes, materials, scene, animations }`.
### useGraph
```typescript
const { nodes, materials } = useGraph(object3D)
```
Traverses an Object3D hierarchy and returns memoized `{ nodes, materials }` collections keyed by name.
---
## Primitives and extend()
### Primitives
Insert pre-existing Three.js objects into the declarative tree:
```jsx
<primitive object={existingMesh} position={[10, 0, 0]} />
```
- NEVER add the same object instance multiple times -- Three.js objects can have only one parent.
- Primitives do NOT auto-dispose; the caller MUST manage lifecycle.
### extend()
Register custom Three.js classes as JSX elements:
```jsx
import { extend } from '@react-three/fiber'
import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls'
extend({ OrbitControls })
// Now usable as <orbitControls args={[camera, domElement]} />
```
The JSX element name is the camelCase version of the registered key.
---
## Event System
R3F implements pointer events via raycasting. Events bubble through the scene graph.
### Supported Events
| Event | Trigger |
|-------|---------|
| `onClick` | Pointer click on mesh |
| `onContextMenu` | Right-click / context menu |
| `onDoubleClick` | Double click |
| `onPointerUp` | Pointer released |
| `onPointerDown` | Pointer pressed |
| `onPointerOver` | Pointer enters mesh (fires continuously) |
| `onPointerOut` | Pointer leaves mesh |
| `onPointerEnter` | Pointer enters mesh (fires once) |
| `onPointerLeave` | Pointer leaves mesh (fires once) |
| `onPointerMove` | Pointer moves over mesh |
| `onPointerMissed` | Click hits no mesh (Canvas-level) |
| `onWheel` | Scroll wheel |
| `onUpdate` | Object receives new props |
### Event Object Properties
| Property | Type | Description |
|----------|------|-------------|
| `object` | `THREE.Object3D` | The mesh actually hit |
| `eventObject` | `THREE.Object3D` | Object with the event handler |
| `point` | `THREE.Vector3` | Intersection in world space |
| `distance` | `number` | Camera-to-intersection distance |
| `uv` | `THREE.Vector2` | UV coordinates at intersection |
| `face` | `THREE.Face` | Intersected face |
| `ray` | `THREE.Ray` | Ray used for intersection |
| `camera` | `THREE.Camera` | Active camera |
| `intersections` | `Intersection[]` | All intersected objects |
| `delta` | `number` | Pixel distance down-to-up |
| `sourceEvent` | `Event` | Original DOM event |
| `stopPropagation()` | `function` | Prevent bubbling to occluded objects |
---
## Performance Patterns
### Disposal
- R3F ALWAYS calls `dispose()` on Three.js objects when components unmount, freeing GPU resources.
- Set `dispose={null}` on an element to PREVENT auto-disposal -- use when objects are shared across components.
### Static Scenes
Use `frameloop="demand"` with `invalidate()` for scenes that do not animate continuously (dashboards, configurators). This saves GPU cycles.
### Portals
```jsx
import { createPortal } from '@react-three/fiber'
createPortal(children, targetScene)
```
Renders children into a different scene/layer without affecting the main scene graph.
### useMemo for Imperative Objects
ALWAYS wrap imperatively created geometries and materials in `useMemo`:
```jsx
const geometry = useMemo(() => new THREE.TorusKnotGeometry(1, 0.3, 128, 32), [])
```
Without `useMemo`, a new object is created on every render.
---
## Reference Links
- [references/methods.md](references/methods.md) -- Hook signatures and Canvas API
- [references/examples.md](references/examples.md) -- Working R3F code examples
- [references/anti-patterns.md](references/anti-patterns.md) -- What NOT to do with R3F
### Official Sources
- https://r3f.docs.pmnd.rs/
- https://r3f.docs.pmnd.rs/api/canvas
- https://r3f.docs.pmnd.rs/api/hooks
- https://r3f.docs.pmnd.rs/api/events
Files in this package (5)
- .gitkeep 1 KB
- SKILL.md 11 KB
- references/anti-patterns.md 7 KB
- references/examples.md 6 KB
- references/methods.md 7 KB
Versions
The database has no other skills named threejs-impl-react-three-fiber.
Database snapshot: 13.11.2026 · package version b99cac06ee0a (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100react-three-fiber
React Three Fiber (R3F) knowledge base — Canvas, JSX scene graph, useFrame, useThree, useLoader, Suspense, @react-three/drei helpers, event system, SSR-safe Next.js integration. Use when building 3D scenes in React/Next.js, integrating drei components (OrbitControls,… - 100react-three-fiber
Builds 3D scenes in React with React Three Fiber (R3F), a React renderer for Three.js where meshes, lights and cameras are JSX components. Use when a user asks to add a 3D scene to a React or Next.js site, build a product configurator, load a GLTF model, animate with useFrame,… - 100three-js
3D graphics in the browser with Three.js and React Three Fiber (R3F). Covers the R3F Canvas, core concepts, the useFrame loop, geometries, materials, lights and the @react-three/drei helpers. USE WHEN: user mentions "Three.js", "React Three Fiber", "R3F", "drei", "useFrame",… - 100threejs-react-three-fiber
Building three.js scenes from React with React Three Fiber and drei: renderer setup, the scene graph as JSX, frame-loop, state and loading hooks, pointer events, and adaptive performance, on WebGL or with WebGPU and TSL. Use when writing React components that render three.js. - 91r3f-animation
React Three Fiber animation - useFrame, useAnimations, spring physics, keyframes. Use when animating objects, playing GLTF animations, creating procedural motion, or implementing physics-based movement. - 100threejs-impl-drei
Use when using Drei helper components with React Three Fiber: controls, environment maps, text rendering, HTML overlays, or performance helpers. Prevents the common mistake of not wrapping useGLTF in Suspense, using wrong Environment preset name, or forgetting makeDefault on…