Skip to content

React Three Fiber Grid Notes

Declarative React renderer for Three.js with zero reconciler overhead, letting you build 3D scenes with components, hooks and suspense.

Grid NotesVersion 9.x3D and visualChecked 2026-11-04
Setup & agent config

Install and prerequisites

What your agent should install or configure before writing code with this pack.
Terminal
npm install three @react-three/fiber && npm install -D @types/three
Packages:three@react-three/fiber@types/three

Use @react-three/fiber@^9 with React 19 (or ^8 with React 18). In Next.js, add transpilePackages: ['three'] to next.config.ts.

Framework setup

Production-ready wiring for React 19, Next.js App Router and Tailwind CSS v4.

On-demand rendering Canvas with reduced-motion fallback

Set frameloop="demand" (or "never" when off-screen) so the GPU isn't pegged at 60 fps when nothing in the 3D scene is moving.

components/scene-canvas.tsx
"use client";

import { useRef } from "react";
import { Canvas, useFrame } from "@react-three/fiber";
import type { Mesh } from "three";

function SpinningCube({ animate }: { animate: boolean }) {
  const meshRef = useRef<Mesh>(null);
  useFrame((_state, delta) => {
    if (!animate || !meshRef.current) return;
    meshRef.current.rotation.y += delta * 0.6;
  });
  return (
    <mesh ref={meshRef}>
      <boxGeometry args={[1.5, 1.5, 1.5]} />
      <meshStandardMaterial color="#4f46e5" />
    </mesh>
  );
}

export function SceneCanvas({ reducedMotion = false }: { reducedMotion?: boolean }) {
  return (
    <div role="img" aria-label="3D preview cube" className="h-64 w-full">
      <Canvas frameloop={reducedMotion ? "demand" : "always"} dpr={[1, 2]}>
        <ambientLight intensity={0.8} />
        <directionalLight position={[3, 4, 5]} intensity={1.2} />
        <SpinningCube animate={!reducedMotion} />
      </Canvas>
    </div>
  );
}

Gotchas for agents

Real-world traps — version mismatches, licence boundaries, main-thread stalls and CSS layer rules — that trip AI agents up.
  1. Never call setState inside useFrame

    useFrame runs on every animation frame (60–120 Hz). Triggering React state updates inside useFrame causes catastrophic re-render lag; mutate ref.current.position / rotation directly instead.

  2. Match R3F major version to React major version

    @react-three/fiber v9 targets React 19's reconciler; v8 targets React 18. Mixing React 19 with R3F v8 throws ReactCurrentOwner runtime errors.

  3. Cap device pixel ratio and frameloop

    Always pass dpr={[1, 2]} to <Canvas> so 3×/4× mobile screens don't render 9–16× the pixels, and use frameloop="demand" whenever the scene only updates on interaction.

Accessibility and reduced motion

How to keep animations and interactive components accessible across keyboard, screen readers and prefers-reduced-motion.

Reduced motion

Switch <Canvas frameloop={reducedMotion ? 'demand' : 'always'}> and guard continuous useFrame camera or mesh motion when prefers-reduced-motion: reduce is active.

Keyboard and screen readers

WebGL canvases are opaque to assistive tech. Give the wrapper role="img" with an aria-label (or @react-three/a11y for interactive 3D objects) so keyboard users can focus and activate controls without a pointer.