React Three Fiber

React Three Fiber (R3F) renders three.js with React: three.js objects are written as JSX, and hooks give access to the render loop and the scene. The project's own docs are bundled in reference/. Read the file that matches the task instead of all of them.

The rules that prevent most problems

These come from the bundled docs; the details and examples are in reference/pitfalls.md and reference/scaling-performance.md.

• Install three and @react-three/fiber. R3F must pair with the matching major version of React, like react-dom does: check the version note in reference/installation.md before choosing versions.
• Do not call setState in useFrame or in fast events. Mutate refs and use the frame delta instead, so the animation does not depend on the frame rate.
• Do not create objects in a loop. Allocate vectors, colours and materials once and reuse them.
• Load assets with useLoader, which caches and suspends, rather than calling a loader in render.
• Reuse geometries and materials, and use instancing for many copies of the same mesh.
• Render on demand (frameloop="demand") when nothing animates all the time, and call invalidate() to draw a frame.
• Mount with care. Toggling visible is cheaper than mounting and unmounting a heavy component.
• In Next.js, add three to transpilePackages in next.config.js (see reference/installation.md). R3F components use hooks and browser APIs, so keep them in a client component ("use client").

Working method

1. Read the file for the task above before writing code, and use the API shown there. R3F changes between major versions.
2. Start from the smallest Canvas that works, check it renders, then add objects, lights and motion.
3. For performance problems, measure first (the performance monitoring section in reference/scaling-performance.md), then apply the matching technique.