Threejs Impl Drei

threejs-impl-drei

Quick Reference

Installation

npm install @react-three/drei @react-three/fiber three

Critical Warnings

ALWAYS wrap components that use loader hooks (useGLTF, useTexture, useFBX, useKTX2, useFont) in ``. Omitting Suspense causes the entire React tree to crash.

ALWAYS add makeDefault to your primary camera controls (`). Without makeDefault`, Drei controls do NOT integrate with R3F's event system and pointer events break.

NEVER use an invalid Environment preset name. The ONLY valid presets are: apartment, city, dawn, forest, lobby, night, park, studio, sunset, warehouse.

NEVER forget to call .preload() for critical assets. Use useGLTF.preload('/model.glb') at module scope to start loading before component mount.

ALWAYS use `` for rendering more than 100 identical meshes. Individual meshes cause one draw call each; instances batch them into one.

---

Controls

OrbitControls

The most common camera control. Orbit, zoom, and pan around a target.

import { OrbitControls } from '@react-three/drei'

Other Controls

| Component | Use Case | |-----------|----------| | CameraControls | Full-featured camera (recommended for complex scenes) | | MapControls | Top-down map navigation (orbit restricted to vertical axis) | | PresentationControls | Drag-to-rotate with spring physics (product viewers) | | ScrollControls | Scroll-driven animation (pages prop sets scroll length) | | TransformControls | Translate/rotate/scale gizmo on selected objects | | DragControls | Drag objects in 3D space | | KeyboardControls | Keyboard input as React context | | FaceControls | Face-tracking camera movement |

ScrollControls Pattern

import { ScrollControls, useScroll } from '@react-three/drei'

  

function ScrollScene() {
  const scroll = useScroll()
  useFrame(() => {
    const offset = scroll.offset // 0 to 1
  })
  return 
}

---

Environment and Staging

Environment

Loads HDR environment maps for realistic reflections and lighting.

import { Environment } from '@react-three/drei'

// Preset (downloads from polyhaven CDN)

// Custom HDR file

// Custom environment with Lightformers

  

Valid presets: apartment, city, dawn, forest, lobby, night, park, studio, sunset, warehouse.

Stage

Complete lighting and shadow setup in one component. Ideal for product viewers.

import { Stage } from '@react-three/drei'

  

Shadow Components

| Component | Use Case | Key Props | |-----------|----------|-----------| | ContactShadows | Soft ground shadows (no light needed) | opacity, scale, blur, far, resolution, color | | AccumulativeShadows | High-quality baked soft shadows | frames, alphaTest, scale, opacity | | RandomizedLight | Child of AccumulativeShadows | amount, radius, intensity, position | | BakeShadows | Bake shadow maps once, stop updating | — | | SoftShadows | PCSS soft shadows for real-time lights | — |

AccumulativeShadows Pattern

Atmosphere

| Component | Purpose | Key Props | |-----------|---------|-----------| | Sky | Procedural sky dome | sunPosition, turbidity, rayleigh | | Stars | Particle starfield | radius, count, factor, fade | | Sparkles | Floating particles | count, size, speed, color | | Cloud | Volumetric clouds | opacity, speed, segments, bounds |

---

Text and HTML

Text (SDF)

High-quality 2D text rendered with signed distance fields via troika-three-text.

import { Text } from '@react-three/drei'

  Hello World

Text3D

Extruded 3D geometry text. Requires a JSON font file (use facetype.js to convert).

import { Text3D, Center } from '@react-three/drei'

  
    Hello
    
  

Html

Renders DOM elements positioned in 3D space.

import { Html } from '@react-three/drei'

  
    Annotation
  

Billboard

ALWAYS faces the camera. Use for labels and sprites.

import { Billboard, Text } from '@react-three/drei'

  Always Visible

Hud

Renders a heads-up display in a separate orthographic scene.

import { Hud, OrthographicCamera } from '@react-three/drei'

  
  HUD Text

---

Materials

| Component | Purpose | |-----------|---------| | MeshReflectorMaterial | Reflective floors with blur, distortion, resolution | | MeshTransmissionMaterial | Glass with chromatic aberration, distortion, thickness | | MeshRefractionMaterial | Refraction using environment cube map | | MeshWobbleMaterial | Animated wobble on MeshStandardMaterial | | MeshDistortMaterial | Perlin noise distortion on MeshStandardMaterial | | MeshDiscardMaterial | Renders nothing (shadow-only objects) | | shaderMaterial | Helper to create custom ShaderMaterial as JSX |

MeshReflectorMaterial Example

shaderMaterial Helper

import { shaderMaterial } from '@react-three/drei'
import { extend } from '@react-three/fiber'

const WaveMaterial = shaderMaterial(
  { uTime: 0, uColor: new THREE.Color(0.2, 0.0, 0.1) },
  /* vertex */ `varying vec2 vUv; void main() { vUv = uv; gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0); }`,
  /* fragment */ `uniform float uTime; uniform vec3 uColor; varying vec2 vUv; void main() { gl_FragColor = vec4(vUv * uColor, 1.0); }`
)
extend({ WaveMaterial })
// Usage: 

---

Loaders

ALWAYS wrap loader-consuming components in ``.

| Hook | Returns | Preload | |------|---------|---------| | useGLTF(url) | { nodes, materials, scene, animations } | useGLTF.preload(url) | | useTexture(url) | THREE.Texture or map object | useTexture.preload(url) | | useFBX(url) | THREE.Group | useFBX.preload(url) | | useKTX2(url) | Compressed texture | useKTX2.preload(url) | | useFont(url) | Font data for Text3D | useFont.preload(url) | | useAnimations(clips, ref) | { actions, names, mixer, ref } | — | | useVideoTexture(url) | THREE.VideoTexture | — |

useGLTF Pattern

import { useGLTF } from '@react-three/drei'

function Model(props) {
  const { nodes, materials } = useGLTF('/model.glb')
  return (
    
      
    
  )
}
useGLTF.preload('/model.glb')

useTexture with Multiple Maps

const textures = useTexture({
  map: '/color.jpg',
  normalMap: '/normal.jpg',
  roughnessMap: '/roughness.jpg',
  aoMap: '/ao.jpg',
})
// Spread directly onto material

useAnimations Pattern

function AnimatedModel() {
  const group = useRef()
  const { nodes, animations } = useGLTF('/character.glb')
  const { actions } = useAnimations(animations, group)

  useEffect(() => {
    actions['Walk']?.play()
    return () => actions['Walk']?.stop()
  }, [actions])

  return 
}

---

Performance

Instances

ALWAYS use for large numbers of identical meshes (>100). Reduces draw calls from N to 1.

import { Instances, Instance } from '@react-three/drei'

  
  
  {positions.map((pos, i) => (
    
  ))}

Merged

Merges different geometries into a single draw call.

import { Merged } from '@react-three/drei'

function Furniture({ nodes }) {
  return (
    
      {(Chair, Table, Lamp) => (
        <>
          
          
          
        
      )}
    
  )
}

Performance Helpers

| Component | Purpose | |-----------|---------| | Detailed | LOD — switches geometry based on camera distance | | BakeShadows | Bakes shadows once, stops updating | | AdaptiveDpr | Lowers device pixel ratio during performance drops | | AdaptiveEvents | Reduces event frequency during performance drops | | PerformanceMonitor | Monitors FPS, triggers regression callbacks | | Bvh | BVH-accelerated raycasting for complex meshes | | meshBounds | Fast bounding-box raycasting (replaces per-triangle) |

PerformanceMonitor Pattern

 setDpr(2)}
  onDecline={() => setDpr(1)}
  flipflops={3}
  onFallback={() => setDpr(0.5)}
/>

---

Staging and Layout

| Component | Purpose | Key Props | |-----------|---------|-----------| | Center | Centers children at origin | top, right, bottom, left, front, back | | Float | Floating hover animation | speed, rotationIntensity, floatIntensity | | Bounds | Auto-fit camera to content | fit, clip, observe, margin | | Resize | Normalizes children to unit size | width, height, depth |

---

Abstractions and Effects

| Component | Purpose | |-----------|---------| | Edges | Renders wireframe edges | | Outlines | Screen-space outlines | | Trail | Motion trail behind objects | | Decal | Project texture onto mesh surface | | Splat | Gaussian splatting renderer | | Clone | Deep clone with shared geometry/materials | | Image | Texture-mapped plane with shader effects | | MeshPortalMaterial | Portal — renders scene inside mesh surface | | GradientTexture | Procedural gradient texture |

---

Gizmos

| Component | Purpose | |-----------|---------| | GizmoHelper | Viewport orientation widget | | PivotControls | Interactive pivot gizmo (translate/rotate/scale) | | TransformControls | Three.js TransformControls wrapper | | Grid | Infinite configurable grid plane | | Helper / useHelper | Visualize light/camera helpers |

---

Component Selection Guide

| Scenario | Component | |----------|-----------| | Product viewer | Stage + OrbitControls + Environment | | Architectural walkthrough | CameraControls + Environment + ContactShadows | | Scrolling experience | ScrollControls + useScroll | | Data visualization | Instances + Html + Billboard | | Text labels in 3D | Text (2D) or Text3D (extruded) + Billboard | | Glass/transparent objects | MeshTransmissionMaterial + Environment | | Reflective floors | MeshReflectorMaterial | | Large identical meshes | Instances (>100) or Merged (mixed geometries) | | Model loading | useGLTF + Suspense + .preload() | | HUD / overlay | Hud or Html with fullscreen |

---

Reference Links

• [references/methods.md](references/methods.md) -- Key component props and hook signatures
• [references/examples.md](references/examples.md) -- Complete working examples
• [references/anti-patterns.md](references/anti-patterns.md) -- Common mistakes and fixes

Official Sources

• https://drei.docs.pmnd.rs/
• https://github.com/pmndrs/drei
• https://r3f.docs.pmnd.rs/

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Impertio-Studio
• Source: Impertio-Studio/Three.js-Claude-Skill-Package
• License: MIT
• Homepage: https://threejs.org/

Install and usage instructions live in the source repository linked above.