three.js

three.js wraps WebGL so you can describe 3D with scenes, cameras, lights, and meshes instead of writing shaders directly. It has the largest ecosystem in web 3D, and AI knows it very well.

Why it is our top pick

• The largest ecosystem. Model loading, post-processing, physics, and controls all have mature solutions, and almost every problem has an answer online.
• Natural in React. React Three Fiber maps three.js objects to JSX components so the scene follows your state; its companion drei provides many common pieces (camera controls, environments, text, and more).
• AI can write it. Describe what you want and the AI produces a working scene. The hard part is performance, which is what the souvenir constrains.

Getting started

pnpm add three @react-three/fiber @react-three/drei

import { Canvas } from '@react-three/fiber';

export function Hero3D() {
  return (
    <Canvas dpr={[1, 2]} frameloop="demand">
      <ambientLight intensity={0.6} />
      <mesh rotation={[0.4, 0.6, 0]}>
        <boxGeometry />
        <meshStandardMaterial color="#ec7a59" />
      </mesh>
    </Canvas>
  );
}

Trade-offs to know

3D is the display component most likely to slow a page down: the library is not small, models and textures are bigger, and continuous rendering drains batteries and heats devices. Follow the constraints in the souvenir below (cap the pixel ratio, render on demand, lazy-load, and provide a static fallback for users who cannot or do not want motion) and 3D stops being a burden.

# 3D scene brief (for your AI)

Use three.js + React Three Fiber to build <scene description> in <location on the page>.

## Performance constraints
- Cap the pixel ratio with `<Canvas dpr={[1, 2]}>`; for static scenes use `frameloop="demand"` so it only renders on change.
- Lazy-load the 3D component with `React.lazy` and mount it when it enters the viewport; show a same-size static placeholder while loading.
- Use compressed glTF (.glb) models under 2 MB each; keep textures at 2048 or smaller.
- Dispose of geometries, materials, and textures when the component unmounts.

## Accessibility and fallbacks
- When the user prefers reduced motion, do not auto-rotate or loop animations; show a still frame.
- If WebGL is unavailable or loading fails, show a static image and keep the rest of the page working.
- Do not put essential information only in the canvas; key text belongs in HTML, not the 3D scene.

## Acceptance
- Scrolling stays smooth on a mid-range phone; first paint is not blocked by 3D assets.