React Three Fiber

npm i three @react-three/fiber @react-three/drei
npm i -D @types/three

 react-dom tree                 R3F tree (inside <Canvas>)
 ─────────────                  ──────────────────────────
 <App>                          <mesh>          → new Mesh()
   <Canvas> ── owns ──►           <boxGeometry> → attach "geometry"
     (canvas, renderer,           <meshStandardMaterial>
      scene, camera,                            → attach "material"
      raycaster, loop)          useFrame(cb)    → runs every frame

import { Canvas } from "@react-three/fiber";
 
export function App() {
  return (
    <Canvas
      camera={{ position: [3, 2, 5], fov: 50 }}
      dpr={[1, 2]}            // clamp devicePixelRatio
      shadows="percentage"    // see note below
      gl={{ antialias: true }}
      frameloop="always"      // | "demand" | "never"
      onPointerMissed={() => select(null)}
    >
      <Scene />
    </Canvas>
  );
}

<mesh position={[0, 1, 0]} rotation-y={Math.PI / 4}
  castShadow>
  <sphereGeometry args={[0.5, 64, 32]} />
  <meshPhysicalMaterial
    color="#88ccff" roughness={0.1} transmission={1}
    thickness={0.5}
  />
</mesh>
<directionalLight position={[5, 8, 3]} intensity={2}
  castShadow shadow-mapSize={[2048, 2048]}
  shadow-camera-far={40} />

import { useRef } from "react";
import type { Mesh, MeshStandardMaterial } from "three";
import { type ThreeElements } from "@react-three/fiber";
 
// component props = the <mesh> element props + yours
type SpinnerProps = ThreeElements["mesh"] & {
  speed?: number;
};
 
export function Spinner(
  { speed = 1, ...props }: SpinnerProps,
) {
  const ref = useRef<Mesh>(null!); // non-null after mount
  const mat = useRef<MeshStandardMaterial>(null!);
  useFrame((_, dt) => {
    ref.current.rotation.y += dt * speed;
  });
  return (
    <mesh ref={ref} {...props}>
      <boxGeometry />
      <meshStandardMaterial ref={mat} color="orange" />
    </mesh>
  );
}

useFrame((state, delta, xrFrame) => {
  ref.current.rotation.x += delta;          // seconds
  ref.current.position.y =
    Math.sin(state.clock.elapsedTime) * 0.3;
});
 
// positive priority: you take over rendering
useFrame(({ gl, scene, camera }) => {
  gl.render(scene, camera);
}, 1);

const camera = useThree((s) => s.camera);  // selector:
const size = useThree((s) => s.size);      // re-render only
const invalidate = useThree((s) => s.invalidate); // when
                                           // that changes

import { Suspense } from "react";
import { useLoader } from "@react-three/fiber";
import { TextureLoader } from "three";
 
function Crate() {
  const map = useLoader(TextureLoader, "/crate.jpg");
  return (
    <mesh>
      <boxGeometry />
      <meshStandardMaterial map={map} />
    </mesh>
  );
}
 
<Suspense fallback={<Spinner />}>
  <Crate />
</Suspense>

import type { ThreeEvent } from "@react-three/fiber";
 
<mesh
  onClick={(e: ThreeEvent<MouseEvent>) => {
    e.stopPropagation();          // nearest hit only
    console.log(e.object.name, e.point, e.distance);
  }}
  onPointerOver={(e) => {
    e.stopPropagation();
    setHover(true);
  }}
  onPointerOut={() => setHover(false)}
/>

npx gltfjsx public/robot.glb --types --transform
# -t/--types      TypeScript definitions
# -T/--transform  draco, prune, resize textures
#                 → writes *-transformed.glb
# -s/--shadows    castShadow + receiveShadow on meshes
# -i/--instance   instance repeated geometry
# -r/--root       path the .glb is served from

// generated (trimmed) — Robot.tsx
type GLTFResult = GLTF & {
  nodes: { Body: THREE.Mesh; Visor: THREE.Mesh };
  materials: { Metal: THREE.MeshStandardMaterial };
};
 
export function Robot(props: ThreeElements["group"]) {
  const { nodes, materials } = useGLTF(
    "/robot-transformed.glb",
  ) as unknown as GLTFResult;
  return (
    <group {...props} dispose={null}>
      <mesh geometry={nodes.Body.geometry}
        material={materials.Metal} />
      <mesh geometry={nodes.Visor.geometry}>
        <meshStandardMaterial color="cyan" />
      </mesh>
    </group>
  );
}
useGLTF.preload("/robot-transformed.glb");

// demand mode: animate only while something moves
function Door({ open }: { open: boolean }) {
  const ref = useRef<Group>(null!);
  const invalidate = useThree((s) => s.invalidate);
  useFrame((_, dt) => {
    const target = open ? -Math.PI / 2 : 0;
    const r = ref.current.rotation;
    r.y += (target - r.y) * Math.min(1, dt * 8);
    if (Math.abs(target - r.y) > 1e-3) invalidate();
  });
  useEffect(() => invalidate(), [open, invalidate]);
  return <group ref={ref}>{/* door mesh */}</group>;
}

import { extend, type ThreeElement }
  from "@react-three/fiber";
import { OrbitControls } from
  "three/addons/controls/OrbitControls.js";
 
// v9 option 1: component factory, no typing needed
const Orbit = extend(OrbitControls);
// <Orbit args={[camera, gl.domElement]} />
 
// option 2: catalog + module augmentation
extend({ OrbitControls });
declare module "@react-three/fiber" {
  interface ThreeElements {
    orbitControls: ThreeElement<typeof OrbitControls>;
  }
}
// <orbitControls args={[camera, gl.domElement]} />

import * as THREE from "three/webgpu";
import {
  Canvas, extend, type ThreeToJSXElements,
} from "@react-three/fiber";
 
declare module "@react-three/fiber" {
  interface ThreeElements
    extends ThreeToJSXElements<typeof THREE> {}
}
extend(THREE as any);
 
<Canvas gl={async (props) => {
  const r = new THREE.WebGPURenderer(props as any);
  await r.init();
  return r;
}}>
  <mesh>
    <boxGeometry />
    <meshStandardNodeMaterial color="orange" />
  </mesh>
</Canvas>

import { useRef, useState } from "react";
import { useFrame, type ThreeElements } from
  "@react-three/fiber";
import { useCursor } from "@react-three/drei";
import type { Mesh } from "three";
 
export function Box(props: ThreeElements["mesh"]) {
  const ref = useRef<Mesh>(null!);
  const [hovered, setHovered] = useState(false);
  const [active, setActive] = useState(false);
  useCursor(hovered);
  useFrame((_, dt) => {
    ref.current.rotation.x += dt * 0.5;
  });
  return (
    <mesh {...props} ref={ref}
      scale={active ? 1.5 : 1}
      onClick={(e) => {
        e.stopPropagation();
        setActive((a) => !a);
      }}
      onPointerOver={(e) => {
        e.stopPropagation();
        setHovered(true);
      }}
      onPointerOut={() => setHovered(false)}>
      <boxGeometry />
      <meshStandardMaterial
        color={hovered ? "hotpink" : "orange"} />
    </mesh>
  );
}

import { Suspense } from "react";
import { Canvas } from "@react-three/fiber";
import {
  Bounds, ContactShadows, Environment, OrbitControls,
  useGLTF,
} from "@react-three/drei";
 
function Model({ url }: { url: string }) {
  const { scene } = useGLTF(url);
  return <primitive object={scene} />;
}
 
export function Viewer({ url }: { url: string }) {
  return (
    <Canvas frameloop="demand" dpr={[1, 2]}
      camera={{ position: [2, 1.5, 3], fov: 40 }}>
      <Suspense fallback={null}>
        <Bounds fit clip observe margin={1.2}>
          <Model url={url} />
        </Bounds>
        <Environment preset="studio" />
        <ContactShadows position-y={-0.5} opacity={0.5}
          blur={2} far={2} />
      </Suspense>
      <OrbitControls makeDefault enableDamping />
    </Canvas>
  );
}

import { useLayoutEffect, useMemo, useRef } from "react";
import type { ThreeEvent } from "@react-three/fiber";
import { Color, InstancedMesh, Object3D } from "three";
 
const N = 50;
const base = new Color("#4f8cff");
const hot = new Color("#ff5a5a");
 
export function Grid() {
  const ref = useRef<InstancedMesh>(null!);
  const dummy = useMemo(() => new Object3D(), []);
  useLayoutEffect(() => {
    for (let i = 0; i < N * N; i++) {
      dummy.position.set(i % N - N / 2, 0,
        Math.floor(i / N) - N / 2);
      dummy.updateMatrix();
      ref.current.setMatrixAt(i, dummy.matrix);
      ref.current.setColorAt(i, base);
    }
    ref.current.instanceMatrix.needsUpdate = true;
    ref.current.computeBoundingSphere();
  }, [dummy]);
 
  const paint = (e: ThreeEvent<PointerEvent>, c: Color) => {
    e.stopPropagation();
    if (e.instanceId === undefined) return;
    ref.current.setColorAt(e.instanceId, c);
    ref.current.instanceColor!.needsUpdate = true;
  };
  return (
    <instancedMesh ref={ref}
      args={[undefined, undefined, N * N]}
      onPointerMove={(e) => paint(e, hot)}
      onPointerOut={(e) => paint(e, base)}>
      <boxGeometry args={[0.9, 0.2, 0.9]} />
      <meshStandardMaterial />
    </instancedMesh>
  );
}

import { useEffect, useRef } from "react";
import { useAnimations, useGLTF } from "@react-three/drei";
import type { Group } from "three";
 
type Clip = "Idle" | "Walk" | "Run";
 
export function Hero({ clip }: { clip: Clip }) {
  const group = useRef<Group>(null!);
  const { scene, animations } = useGLTF("/hero.glb");
  const { actions } = useAnimations(animations, group);
 
  useEffect(() => {
    const a = actions[clip];
    a?.reset().fadeIn(0.25).play();
    return () => { a?.fadeOut(0.25); };
  }, [clip, actions]);
 
  return <primitive ref={group} object={scene} />;
}
useGLTF.preload("/hero.glb");

import { useControls } from "leva";
 
export function Tuned() {
  const { color, roughness, metalness, env } = useControls({
    color: "#ff8844",
    roughness: { value: 0.4, min: 0, max: 1 },
    metalness: { value: 0, min: 0, max: 1 },
    env: { value: 1, min: 0, max: 3 },
  });
  return (
    <mesh>
      <torusKnotGeometry args={[0.6, 0.2, 128, 16]} />
      <meshStandardMaterial color={color}
        roughness={roughness} metalness={metalness}
        envMapIntensity={env} />
    </mesh>
  );
}