# React Three Fiber
+
+Build declarative 3D scenes with React. React Three Fiber (R3F, package: @react-three/fiber) is a React renderer for Three.js — every Three.js object becomes a JSX element. Combined with drei (a companion library of pre-built helpers), R3F makes it practical to ship production 3D inside React apps: product configurators, hero scenes, data visualizations, interactive portfolios, and immersive experiences.
−Build declarative 3D scenes with React. React Three Fiber (R3F) is a React renderer for Three.js — every Three.js object becomes a JSX element. Combined with drei (a companion library of pre-built helpers), R3F makes it practical to ship production 3D inside React apps: product configurators, hero scenes, data visualizations, interactive portfolios, and immersive experiences.
+Note: the R3F ecosystem is actively evolving. As of the writing of this update, pmndrs has published a v10 alpha of @react-three/fiber (adds WebGPU support, a new scheduler, and renames state.gl to state.renderer) and drei has v11 alpha with helper updates. See the Compatibility & migration section below for concrete guidance and links to the release notes.
## When to use
@@ −17 +19 @@
- Non-React projects — use plain Three.js (threejs-webgl skill)
- Game-engine-level physics, collisions, and entity systems — consider Babylon.js or PlayCanvas
- When the 3D adds no value and a well-shot photo or illustration would work better
−- Server-side rendering requirements — R3F renders on the client only
+- Server-side rendering requirements — R3F is client-only (see SSR guidance below)
## Core concepts
### Canvas
+
+The root component that creates a renderer, scene, and camera. Past R3F versions exposed the WebGL renderer via `state.gl`; newer versions (v10 alpha) rename this to `state.renderer` and add first-class WebGPU support. R3F lets you provide a `gl` prop to Canvas — it can be a renderer constructor, a renderer instance, or an async callback that returns a renderer (required for WebGPU's async initialization).
−The root component that creates a WebGL renderer, scene, and camera:
+Basic WebGL example:
```tsx
import { Canvas } from "@react-three/fiber";
@@ −35 +39 @@
<boxGeometry args={[1, 1, 1]} />
<meshStandardMaterial color="hotpink" />
</mesh>
+</Canvas>
+```
+
+Async WebGPU initialization pattern (supported via async `gl` prop):
+
+```tsx
+import * as THREE from 'three/webgpu';
+import { Canvas } from '@react-three/fiber';
+
+<Canvas
+ gl={async (props) => {
+ const renderer = new THREE.WebGPURenderer(props as any);
+ await renderer.init(); // WebGPU renderer needs async init
+ return renderer;
+ }}
+>
+ {/* scene */}
</Canvas>
```
+
+(See the R3F docs and release notes for migration examples and details.)
+
+### useFrame (per-frame updates)
−### useFrame
+`useFrame` remains the mechanism for per-frame updates. The core guidance stands — avoid calling React setState every frame; mutate refs instead. Newer R3F versions introduce an improved scheduler that gives `useFrame` advanced scheduling options and the ability to register frame callbacks outside of `<Canvas />` (use cases: render orchestration, headless loops). If you rely on scheduler-specific behavior, consult the release notes for the scheduler API and options.
−Per-frame updates. Never call `setState` here — mutate refs directly:
+Example (still prefer refs for per-frame mutation):
```tsx
+import { useFrame } from '@react-three/fiber';
−import { useFrame } from "@react-three/fiber";
+import { useRef } from 'react';
−import { useRef } from "react";
−import type { Mesh } from "three";
function SpinningBox() {
− const meshRef = useRef<Mesh>(null);
+ const meshRef = useRef(null);
useFrame((_, delta) => {
if (meshRef.current) meshRef.current.rotation.y += delta * 0.5;
});
@@ −60 +84 @@
);
}
```
+
+### Model loading with useGLTF / useLoader
−### Model loading with useGLTF
+Drei continues to supply helpers like `useGLTF`. Best practice remains: wrap loads in `<Suspense>` and call `useGLTF.preload()` for assets you want downloaded early. From R3F v9 onward, `useLoader` accepts loader instances (useful for pooling or custom loader configuration).
```tsx
−import { useGLTF } from "@react-three/drei";
+import { useGLTF } from '@react-three/drei';
function Model({ url }: { url: string }) {
const { scene } = useGLTF(url);
return <primitive object={scene} />;
}
−useGLTF.preload("/models/product.glb");
+useGLTF.preload('/models/product.glb');
```
+
+### Environment, lighting, and drei helpers
−### Environment and lighting with drei
+Drei remains the recommended source for ready-made helpers: `Environment`, `ContactShadows`, `OrbitControls`, `Text`, `Float`, `Instances`, etc. Drei v11 (alpha) introduces helper updates and WebGPU-ready helpers; pin or test helper versions when upgrading. Use `Environment` for IBL reflections and `ContactShadows` for soft ground shadows.
−```tsx
