---
name: drei
description: >-
You are an expert in @react-three/drei, the companion library for React
Three Fiber that provides 100+ ready-made components and hooks for common 3D
patterns. You help developers add orbit controls, environment maps, text
rendering, HTML overlays, loaders, performance utilities, shaders, and
abstractions — eliminating boilerplate and letting teams focus on creative
work instead of Three.js plumbing.
license: Apache-2.0
compatibility: ''
metadata:
author: terminal-skills
version: 1.0.0
category: 3D & Creative
tags:
- 3d
- react
- threejs
- helpers
- controls
- abstractions
- r3f
---
# Drei — Essential Helpers for React Three Fiber
You are an expert in @react-three/drei, the companion library for React Three Fiber that provides 100+ ready-made components and hooks for common 3D patterns. You help developers add orbit controls, environment maps, text rendering, HTML overlays, loaders, performance utilities, shaders, and abstractions — eliminating boilerplate and letting teams focus on creative work instead of Three.js plumbing.
## Core Capabilities
### Controls
```tsx
import { OrbitControls, MapControls, FlyControls, ScrollControls } from "@react-three/drei";
// Orbit around an object (product viewer)
// Map-style controls (top-down, pan + zoom)
// Fly through scene (game, architectural viz)
// Scroll-linked animation (landing pages)
{/* useScroll() inside to read scroll position */}
```
### Environment and Lighting
```tsx
import { Environment, Lightformer, Sky, Stars, Stage } from "@react-three/drei";
// HDR environment map (realistic reflections)
// Custom studio lighting
// Quick product staging (auto lighting + shadows)
// Procedural sky
```
### Text and HTML
```tsx
import { Text, Text3D, Html, Billboard } from "@react-three/drei";
// 2D text in 3D space (SDF rendering, crisp at any distance)
Hello World
// Extruded 3D text (geometry)
3D TEXT
// HTML DOM elements in 3D space
Product Info
// Always face camera
Always visible
```
### Loaders and Assets
```tsx
import { useGLTF, useTexture, useVideoTexture, useFBX, Preload } from "@react-three/drei";
// GLTF model
const { scene, nodes, materials } = useGLTF("/model.glb");
// Textures (with auto-disposal)
const [colorMap, normalMap, roughnessMap] = useTexture([
"/textures/color.jpg",
"/textures/normal.jpg",
"/textures/roughness.jpg",
]);
// Video as texture (for screens, billboards)
const videoTexture = useVideoTexture("/video/demo.mp4");
// Preload all assets inside Canvas
```
### Shapes and Helpers
```tsx
import {
RoundedBox, Sphere, Torus, Line, QuadraticBezierLine,
Float, MeshWobbleMaterial, MeshDistortMaterial, ContactShadows,
Grid, GizmoHelper, GizmoViewport,
} from "@react-three/drei";
// Pre-built geometries
// Animated materials
// Floating animation
// Ground shadows (no shadow plane needed)
// Debug grid
```
### Performance
```tsx
import { AdaptiveDpr, AdaptiveEvents, PerformanceMonitor, Instances, Detailed } from "@react-three/drei";
// Auto-adjust quality
setDpr(0.5)} onIncline={() => setDpr(1)} />
// LOD (Level of Detail)
{/* Close */}
{/* Medium */}
{/* Far */}
// GPU instancing for 1000s of objects
{positions.map((pos, i) => )}
```
## Installation
```bash
npm install @react-three/drei
# Peer dependency: @react-three/fiber three
```
## Best Practices
1. **Stage for quick setup** — Use `` to get instant professional lighting and shadows for product shots
2. **Environment for reflections** — Always add ``; PBR materials look flat without it
3. **Html for UI in 3D** — Use `` for tooltips, labels, buttons; `occlude` hides them behind 3D objects
4. **Float for motion** — Wrap any object in `` for gentle floating animation; great for hero sections
5. **ContactShadows** — Cheaper than real shadows; place below objects for grounding effect
6. **Instances for performance** — Use `` for forests, particle fields, city blocks; 100x faster than individual meshes
7. **Preload assets** — Add `` inside Canvas; assets load before scene renders
8. **ScrollControls for landing pages** — Scroll-linked 3D animations without external libraries; `useScroll()` gives normalized progress