three.js User Guide

three.js is a JavaScript 3D graphics library that creates and renders interactive 3D scenes in the browser using WebGL and WebGPU. It provides a complete scene graph, physically-based materials, dozens of geometry primitives, animation, audio, model loading, and post-processing — all with zero runtime dependencies.

This guide covers three.js v0.184.0 (revision r184).

1. Quick Start

Get a spinning cube on screen in under two minutes.

1.1 Minimal HTML Setup

Create a single HTML file:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <title>three.js Quick Start</title>
  <style>
    body { margin: 0; }
    canvas { display: block; }
  </style>
</head>
<body>
  <script type="importmap">
    {
      "imports": {
        "three": "https://unpkg.com/three@0.184.0/build/three.module.js",
        "three/addons/": "https://unpkg.com/three@0.184.0/examples/jsm/"
      }
    }
  </script>
  <script type="module">
    import * as THREE from 'three';

    // Scene
    const scene = new THREE.Scene();

    // Camera
    const camera = new THREE.PerspectiveCamera(
      75,                                    // field of view (degrees)
      window.innerWidth / window.innerHeight, // aspect ratio
      0.1,                                   // near clipping plane
      1000                                   // far clipping plane
    );
    camera.position.z = 5;

    // Renderer
    const renderer = new THREE.WebGLRenderer();
    renderer.setSize(window.innerWidth, window.innerHeight);
    document.body.appendChild(renderer.domElement);

    // Mesh = Geometry + Material
    const geometry = new THREE.BoxGeometry(1, 1, 1);
    const material = new THREE.MeshBasicMaterial({ color: 0x00ff00 });
    const cube = new THREE.Mesh(geometry, material);
    scene.add(cube);

    // Animation loop
    function animate() {
      cube.rotation.x += 0.01;
      cube.rotation.y += 0.01;
      renderer.render(scene, camera);
    }
    renderer.setAnimationLoop(animate);
  </script>
</body>
</html>

Open this file in any modern browser. You will see a rotating green cube.

Tip

Use renderer.setAnimationLoop(callback) instead of manual requestAnimationFrame calls. It handles the loop lifecycle automatically and is required for WebXR compatibility.

1.2 The Three Pillars

Every three.js application requires exactly three objects:

The render call brings them together: renderer.render(scene, camera).

1.3 What Goes Into a Scene

Scene
├── Mesh (geometry + material)
├── Light (ambient, directional, point, spot, ...)
├── Group
│   ├── Mesh
│   └── Mesh
├── Camera
├── Sprite
├── Line / LineSegments
├── Points
└── Audio / PositionalAudio

All visible objects extend Object3D, which provides position, rotation, scale, visible, parent, children, and the add() / remove() methods that form the scene graph hierarchy.

2. Installation

2.1 npm (Recommended)

npm install three

Then import in your JavaScript or TypeScript modules:

import * as THREE from 'three';

Important

three.js is an ES module package ("type": "module" in its package.json). Use import syntax, not require(). If your bundler or Node.js configuration expects CommonJS, you will need to configure it for ESM interop.

2.2 Package Exports

The three package exposes several entry points:

// Import core + WebGPURenderer
import * as THREE from 'three/webgpu';

// Import a specific addon
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';

2.3 CDN / Import Maps

For prototyping without a build tool, use an import map in your HTML:

<script type="importmap">
  {
    "imports": {
      "three": "https://unpkg.com/three@0.184.0/build/three.module.js",
      "three/addons/": "https://unpkg.com/three@0.184.0/examples/jsm/"
    }
  }
</script>
<script type="module">
  import * as THREE from 'three';
  import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
</script>

Warning

Never load three.js from multiple sources (e.g., mixing a CDN copy with an npm copy). The library detects this and warns: "WARNING: Multiple instances of Three.js being imported." Duplicate instances cause type checks to fail silently — materials, geometries, and textures from one instance are incompatible with renderers from another.

2.4 Development Server

If you clone the three.js repository for development or to run examples:

git clone https://github.com/mrdoob/three.js.git
cd three.js
npm install
npm start

This starts a dev server on port 8080 with live reloading. Other npm scripts:

2.5 Browser Requirements

three.js requires WebGL 2 at minimum (WebGL 1 support was removed in r163).

3. Configuration

three.js has no configuration files. All setup is programmatic through constructor parameters and object properties.

3.1 WebGLRenderer Options

const renderer = new THREE.WebGLRenderer({
  canvas: document.getElementById('myCanvas'),  // existing canvas element
  antialias: true,           // smooth edges (default: false)
  alpha: true,               // transparent background (default: false)
  premultipliedAlpha: true,  // (default: true)
  preserveDrawingBuffer: false, // set true for screenshots (default: false)
  powerPreference: 'high-performance', // GPU hint: 'default', 'high-performance', 'low-power'
  stencil: true,             // stencil buffer (default: true)
  depth: true,               // depth buffer (default: true)
  logarithmicDepthBuffer: false, // reduces z-fighting for large scenes
});

After construction, configure rendering behavior:

renderer.setSize(window.innerWidth, window.innerHeight);
renderer.setPixelRatio(window.devicePixelRatio);

// Tone mapping for HDR content
renderer.toneMapping = THREE.ACESFilmicToneMapping;
renderer.toneMappingExposure = 1.0;

// Color management
renderer.outputColorSpace = THREE.SRGBColorSpace;

// Shadows
renderer.shadowMap.enabled = true;
renderer.shadowMap.type = THREE.PCFSoftShadowMap;

3.2 WebGPURenderer Setup

import * as THREE from 'three/webgpu';

const renderer = new THREE.WebGPURenderer({ antialias: true });
renderer.setSize(window.innerWidth, window.innerHeight);
renderer.setPixelRatio(window.devicePixelRatio);
document.body.appendChild(renderer.domElement);

// WebGPURenderer requires explicit initialization
await renderer.init();

renderer.setAnimationLoop(animate);

Important

WebGPURenderer requires calling await renderer.init() before the first render. Calling .render() before .init() throws: "Renderer: .render() called before the backend is initialized. Use .init() first."

3.3 Scene Defaults

const scene = new THREE.Scene();
scene.background = new THREE.Color(0x222222);      // solid color
// OR
scene.background = cubeTexture;                     // skybox (CubeTexture)
// OR
scene.background = equirectTexture;                 // equirectangular HDR

scene.fog = new THREE.Fog(0xcccccc, 10, 100);      // linear fog: color, near, far
// OR
scene.fog = new THREE.FogExp2(0xcccccc, 0.02);     // exponential fog: color, density

scene.environment = pmremTexture;                    // IBL for all PBR materials

4. Core Usage

4.1 Creating Scenes and Adding Objects

The Scene Graph

Scene extends Object3D. Every object added to the scene (or to a child of the scene) becomes part of a hierarchical tree. Transforms cascade: a child inherits its parent's position, rotation, and scale.

const scene = new THREE.Scene();

// Group objects for collective transforms
const carGroup = new THREE.Group();
carGroup.position.set(0, 0.5, 0);
scene.add(carGroup);

const body = new THREE.Mesh(
  new THREE.BoxGeometry(2, 0.5, 1),
  new THREE.MeshStandardMaterial({ color: 0x2244aa })
);
carGroup.add(body);

const wheel = new THREE.Mesh(
  new THREE.CylinderGeometry(0.2, 0.2, 0.1, 16),
  new THREE.MeshStandardMaterial({ color: 0x111111 })
);
wheel.position.set(-0.6, -0.3, 0.5);
wheel.rotation.z = Math.PI / 2;
carGroup.add(wheel);

// Rotating carGroup rotates both body and wheel together
carGroup.rotation.y = Math.PI / 4;

Object3D Properties

Every scene object inherits these from Object3D:

Key methods:

object.add(child);                     // add child to scene graph
object.remove(child);                  // remove child
object.getObjectByName('wheel');       // find descendant by name
object.traverse(callback);            // walk all descendants
object.lookAt(x, y, z);               // orient toward a point
object.localToWorld(vec3);             // convert local → world coords
object.worldToLocal(vec3);             // convert world → local coords
object.getWorldPosition(targetVec3);   // get world-space position
object.getWorldQuaternion(targetQuat); // get world-space rotation

Note

lookAt() uses the object's up property (default Vector3(0, 1, 0)) to determine which direction is "up." For cameras, this usually works as expected. For meshes, you may need to adjust up if the model's local orientation differs.

4.2 Geometries

Geometries define the shape of 3D objects as vertices, normals, and UVs stored in BufferAttribute arrays. All built-in geometries extend BufferGeometry.

Primitive Geometries

// Box: width, height, depth, widthSegments, heightSegments, depthSegments
new THREE.BoxGeometry(1, 1, 1, 1, 1, 1);

// Sphere: radius, widthSegments, heightSegments, phiStart, phiLength, thetaStart, thetaLength
new THREE.SphereGeometry(1, 32, 16);

// Plane: width, height, widthSegments, heightSegments
new THREE.PlaneGeometry(10, 10, 1, 1);

// Circle: radius, segments, thetaStart, thetaLength
new THREE.CircleGeometry(1, 32);

// Cylinder: radiusTop, radiusBottom, height, radialSegments, heightSegments, openEnded
new THREE.CylinderGeometry(0.5, 0.5, 2, 32);

// Cone: radius, height, radialSegments, heightSegments, openEnded
new THREE.ConeGeometry(0.5, 2, 32);

// Torus: radius, tube, radialSegments, tubularSegments, arc
new THREE.TorusGeometry(1, 0.3, 16, 48);

// TorusKnot: radius, tube, tubularSegments, radialSegments, p, q
new THREE.TorusKnotGeometry(1, 0.3, 100, 16);

// Capsule: radius, length, capSegments, radialSegments
new THREE.CapsuleGeometry(0.5, 1, 10, 20);

// Ring: innerRadius, outerRadius, thetaSegments, phiSegments
new THREE.RingGeometry(0.5, 1, 32);

// Platonic solids: radius, detail
new THREE.DodecahedronGeometry(1, 0);
new THREE.IcosahedronGeometry(1, 0);
new THREE.OctahedronGeometry(1, 0);
new THREE.TetrahedronGeometry(1, 0);

Extruded and Lathed Geometries

// Extrude a 2D shape into 3D
const shape = new THREE.Shape();
shape.moveTo(0, 0);
shape.lineTo(1, 0);
shape.lineTo(1, 1);
shape.lineTo(0, 1);
shape.lineTo(0, 0);

const extrudeGeometry = new THREE.ExtrudeGeometry(shape, {
  depth: 0.5,
  bevelEnabled: true,
  bevelThickness: 0.1,
  bevelSize: 0.1,
  bevelSegments: 3,
});

// Lathe: revolve a 2D profile around the Y axis
const points = [];
for (let i = 0; i < 10; i++) {
  points.push(new THREE.Vector2(Math.sin(i * 0.2) * 0.5 + 0.5, i * 0.2));
}
const latheGeometry = new THREE.LatheGeometry(points, 32);

// Tube: extrude along a 3D curve
const curve = new THREE.CatmullRomCurve3([
  new THREE.Vector3(-1, 0, 0),
  new THREE.Vector3(0, 1, 0),
  new THREE.Vector3(1, 0, 0),
]);
const tubeGeometry = new THREE.TubeGeometry(curve, 64, 0.1, 8, false);

Custom BufferGeometry

const geometry = new THREE.BufferGeometry();

const vertices = new Float32Array([
  -1, -1, 0,
   1, -1, 0,
   0,  1, 0,
]);
geometry.setAttribute('position', new THREE.BufferAttribute(vertices, 3));

// Optional: add normals, UVs, colors
const normals = new Float32Array([0, 0, 1, 0, 0, 1, 0, 0, 1]);
geometry.setAttribute('normal', new THREE.BufferAttribute(normals, 3));

// Indexed geometry (shared vertices)
const indices = new Uint16Array([0, 1, 2]);
geometry.setIndex(new THREE.BufferAttribute(indices, 1));

geometry.computeBoundingSphere();

Warning

BufferAttribute requires typed arrays (Float32Array, Uint16Array, etc.). Passing a regular JavaScript array triggers: "THREE.BufferAttribute: array should be a Typed Array."

Wireframe and Edge Views

// Show wireframe of any geometry
const wireframe = new THREE.WireframeGeometry(boxGeometry);
const line = new THREE.LineSegments(wireframe);
scene.add(line);

// Show only hard edges (angle threshold)
const edges = new THREE.EdgesGeometry(boxGeometry, 15); // 15-degree threshold
const edgeLine = new THREE.LineSegments(
  edges,
  new THREE.LineBasicMaterial({ color: 0x000000 })
);
scene.add(edgeLine);

4.3 Materials

Materials define how surfaces appear. All materials extend the Material base class.

Material Comparison

PBR Materials (MeshStandardMaterial)

const material = new THREE.MeshStandardMaterial({
  color: 0xffffff,          // base color (albedo)
  metalness: 0.0,           // 0 = dielectric, 1 = metal
  roughness: 0.5,           // 0 = mirror, 1 = fully rough
  map: colorTexture,        // albedo texture
  normalMap: normalTexture,  // surface detail via normals
  roughnessMap: roughTex,    // per-pixel roughness
  metalnessMap: metalTex,    // per-pixel metalness
  aoMap: aoTexture,          // ambient occlusion
  aoMapIntensity: 1.0,
  emissive: 0x000000,        // self-illumination color
  emissiveMap: emissiveTex,
  emissiveIntensity: 1.0,
  envMap: envTexture,         // environment reflection (or use scene.environment)
  envMapIntensity: 1.0,
  displacementMap: dispTex,   // vertex displacement
  displacementScale: 0.1,
  alphaMap: alphaTex,         // per-pixel opacity
  transparent: true,
  opacity: 1.0,
  side: THREE.DoubleSide,     // FrontSide, BackSide, DoubleSide
  flatShading: false,
  wireframe: false,
});

MeshPhysicalMaterial (Advanced PBR)

Extends MeshStandardMaterial with additional properties:

const glassMaterial = new THREE.MeshPhysicalMaterial({
  color: 0xffffff,
  metalness: 0,
  roughness: 0,
  transmission: 1.0,          // 0 = opaque, 1 = fully transparent glass
  thickness: 0.5,             // thickness for refraction
  ior: 1.5,                   // index of refraction
  clearcoat: 0.0,             // clear lacquer layer (car paint)
  clearcoatRoughness: 0.0,
  sheen: 0.0,                 // fabric-like sheen
  sheenRoughness: 0.5,
  sheenColor: new THREE.Color(0xffffff),
  iridescence: 0.0,           // thin-film iridescence (soap bubbles)
  iridescenceIOR: 1.3,
});

Line and Point Materials

// Lines
new THREE.LineBasicMaterial({ color: 0xff0000, linewidth: 1 });
new THREE.LineDashedMaterial({ color: 0xff0000, dashSize: 0.3, gapSize: 0.1 });

// Points
new THREE.PointsMaterial({ color: 0x00ff00, size: 0.1, sizeAttenuation: true });

// Sprites (always face camera)
new THREE.SpriteMaterial({ map: spriteTexture, color: 0xffffff });

Common Material Properties

All materials share these properties:

material.transparent = true;   // enable alpha blending
material.opacity = 0.5;        // global opacity (requires transparent: true)
material.side = THREE.DoubleSide; // render both faces
material.depthWrite = true;    // write to depth buffer
material.depthTest = true;     // test against depth buffer
material.visible = true;       // skip rendering entirely
material.blending = THREE.NormalBlending; // blending mode
material.needsUpdate = true;   // force shader recompilation after changing defines

ShaderMaterial (Custom Shaders)

const material = new THREE.ShaderMaterial({
  uniforms: {
    uTime: { value: 0 },
    uColor: { value: new THREE.Color(0xff0000) },
    uTexture: { value: texture },
  },
  vertexShader: `
    uniform float uTime;
    varying vec2 vUv;
    void main() {
      vUv = uv;
      vec3 pos = position;
      pos.z += sin(pos.x * 5.0 + uTime) * 0.1;
      gl_Position = projectionMatrix * modelViewMatrix * vec4(pos, 1.0);
    }
  `,
  fragmentShader: `
    uniform vec3 uColor;
    uniform sampler2D uTexture;
    varying vec2 vUv;
    void main() {
      vec4 texColor = texture2D(uTexture, vUv);
      gl_FragColor = vec4(uColor * texColor.rgb, 1.0);
    }
  `,
  transparent: false,
  side: THREE.DoubleSide,
});

// Update in animation loop
material.uniforms.uTime.value = elapsedTime;

4.4 Textures

Loading Textures

const textureLoader = new THREE.TextureLoader();

// Basic loading
const texture = textureLoader.load('/textures/wood.jpg');

// With callbacks
const texture = textureLoader.load(
  '/textures/wood.jpg',
  (texture) => { console.log('Loaded'); },       // onLoad
  (xhr) => { console.log(xhr.loaded / xhr.total * 100 + '%'); }, // onProgress
  (err) => { console.error('Error:', err); }      // onError
);

Texture Properties

texture.wrapS = THREE.RepeatWrapping;    // horizontal: ClampToEdgeWrapping, RepeatWrapping, MirroredRepeatWrapping
texture.wrapT = THREE.RepeatWrapping;    // vertical
texture.repeat.set(4, 4);               // tile 4x4
texture.offset.set(0.5, 0.5);           // UV offset
texture.rotation = Math.PI / 4;         // rotate UVs
texture.center.set(0.5, 0.5);           // rotation center

texture.magFilter = THREE.LinearFilter;  // magnification filter
texture.minFilter = THREE.LinearMipmapLinearFilter; // minification filter
texture.generateMipmaps = true;

texture.colorSpace = THREE.SRGBColorSpace; // for color maps (albedo, emissive)
// Leave as LinearSRGBColorSpace for data maps (normal, roughness, metalness, ao)

texture.flipY = true;                    // flip vertically (default true for image loads)

Cube Textures (Skybox / Environment)

const cubeLoader = new THREE.CubeTextureLoader();
const envMap = cubeLoader.load([
  'px.jpg', 'nx.jpg',  // positive-x, negative-x
  'py.jpg', 'ny.jpg',  // positive-y, negative-y
  'pz.jpg', 'nz.jpg',  // positive-z, negative-z
]);

scene.background = envMap;
scene.environment = envMap;  // applies as IBL to all PBR materials

LoadingManager

Track loading progress across multiple assets:

const manager = new THREE.LoadingManager();
manager.onStart = (url, loaded, total) => {
  console.log(`Started loading: ${url}. ${loaded}/${total} files.`);
};
manager.onProgress = (url, loaded, total) => {
  console.log(`Loading: ${loaded}/${total}`);
};
manager.onLoad = () => {
  console.log('All assets loaded');
};
manager.onError = (url) => {
  console.error('Error loading:', url);
};

const textureLoader = new THREE.TextureLoader(manager);
const gltfLoader = new GLTFLoader(manager);
// All loaders sharing this manager contribute to progress

4.5 Lighting

Without lights, only MeshBasicMaterial, MeshNormalMaterial, and MeshMatcapMaterial are visible. All other materials require at least one light.

Light Types

// Ambient: uniform illumination from all directions (no shadows)
const ambient = new THREE.AmbientLight(0x404040, 1.0); // color, intensity
scene.add(ambient);

// Hemisphere: sky color from above, ground color from below (no shadows)
const hemi = new THREE.HemisphereLight(0x87ceeb, 0x362907, 1.0);
scene.add(hemi);

// Directional: parallel rays (sun-like, casts shadows)
const dir = new THREE.DirectionalLight(0xffffff, 1.5);
dir.position.set(5, 10, 7);
scene.add(dir);

// Point: emits in all directions from a position (casts shadows)
const point = new THREE.PointLight(0xff9900, 2, 50, 2); // color, intensity, distance, decay
point.position.set(0, 3, 0);
scene.add(point);

// Spot: cone-shaped (casts shadows)
const spot = new THREE.SpotLight(0xffffff, 2);
spot.position.set(0, 10, 0);
spot.angle = Math.PI / 6;    // cone angle
spot.penumbra = 0.3;          // soft edge (0-1)
spot.decay = 2;
spot.distance = 50;
spot.target.position.set(0, 0, 0); // aim point
scene.add(spot);
scene.add(spot.target);

// RectArea: rectangular light (area light, no shadows, PhysicalMaterial only)
const rect = new THREE.RectAreaLight(0xffffff, 5, 4, 2); // color, intensity, width, height
rect.position.set(0, 5, 0);
rect.lookAt(0, 0, 0);
scene.add(rect);

Shadow Setup

Shadows require configuration on the renderer, the light, and each object:

// 1. Enable on renderer
renderer.shadowMap.enabled = true;
renderer.shadowMap.type = THREE.PCFSoftShadowMap;

// 2. Enable on light
dirLight.castShadow = true;
dirLight.shadow.mapSize.width = 2048;   // resolution
dirLight.shadow.mapSize.height = 2048;
dirLight.shadow.camera.near = 0.5;
dirLight.shadow.camera.far = 50;
// For DirectionalLight, shadow camera is orthographic:
dirLight.shadow.camera.left = -10;
dirLight.shadow.camera.right = 10;
dirLight.shadow.camera.top = 10;
dirLight.shadow.camera.bottom = -10;
dirLight.shadow.bias = -0.001;          // reduce shadow acne

// 3. Enable on objects
mesh.castShadow = true;
floor.receiveShadow = true;

Tip

Use CameraHelper to visualize a shadow camera's frustum and debug shadow coverage: scene.add(new THREE.CameraHelper(dirLight.shadow.camera));

4.6 Cameras

PerspectiveCamera

const camera = new THREE.PerspectiveCamera(
  75,    // fov: vertical field of view in degrees
  window.innerWidth / window.innerHeight, // aspect ratio
  0.1,   // near plane
  1000   // far plane
);
camera.position.set(0, 5, 10);
camera.lookAt(0, 0, 0);

OrthographicCamera

const frustumSize = 10;
const aspect = window.innerWidth / window.innerHeight;
const camera = new THREE.OrthographicCamera(
  -frustumSize * aspect / 2,  // left
   frustumSize * aspect / 2,  // right
   frustumSize / 2,           // top
  -frustumSize / 2,           // bottom
  0.1,                        // near
  1000                        // far
);
camera.position.set(5, 5, 5);
camera.lookAt(0, 0, 0);

CubeCamera (for dynamic reflections)

const cubeRenderTarget = new THREE.WebGLCubeRenderTarget(256);
const cubeCamera = new THREE.CubeCamera(0.1, 100, cubeRenderTarget);
scene.add(cubeCamera);

const reflectiveMaterial = new THREE.MeshStandardMaterial({
  envMap: cubeRenderTarget.texture,
  metalness: 1,
  roughness: 0,
});

// In animation loop: update before main render
cubeCamera.position.copy(reflectiveMesh.position);
cubeCamera.update(renderer, scene);
renderer.render(scene, camera);

4.7 Animation

AnimationMixer

three.js uses a mixer-based animation system. Models loaded from GLTF/FBX files typically include AnimationClip data.

let mixer;

const loader = new GLTFLoader();
loader.load('model.glb', (gltf) => {
  const model = gltf.scene;
  scene.add(model);

  mixer = new THREE.AnimationMixer(model);

  // Play the first animation clip
  const clip = gltf.animations[0];
  const action = mixer.clipAction(clip);
  action.play();

  // Play all animations
  gltf.animations.forEach((clip) => {
    mixer.clipAction(clip).play();
  });
});

// In animation loop:
const clock = new THREE.Clock();
function animate() {
  const delta = clock.getDelta();
  if (mixer) mixer.update(delta);
  renderer.render(scene, camera);
}

AnimationAction Controls

const action = mixer.clipAction(clip);

// Playback control
action.play();
action.stop();
action.reset();
action.paused = true;

// Speed and direction
action.timeScale = 1.0;      // 1 = normal, 2 = double speed, -1 = reverse
action.setEffectiveTimeScale(0.5);

// Weight (for blending)
action.setEffectiveWeight(1.0);

// Loop modes
action.loop = THREE.LoopRepeat;     // default: loops forever
action.loop = THREE.LoopOnce;       // play once
action.loop = THREE.LoopPingPong;   // forward then backward
action.clampWhenFinished = true;     // hold last frame (with LoopOnce)
action.repetitions = 3;             // play 3 times

// Crossfade between animations
const walkAction = mixer.clipAction(walkClip);
const runAction = mixer.clipAction(runClip);
walkAction.play();
walkAction.crossFadeTo(runAction, 0.5, true); // target, duration, warp
runAction.play();

AnimationClip Events

mixer.addEventListener('finished', (event) => {
  console.log('Animation finished:', event.action.getClip().name);
});

mixer.addEventListener('loop', (event) => {
  console.log('Animation looped:', event.action.getClip().name);
});

Programmatic Animation

For simple animations without clips, manipulate properties directly:

const clock = new THREE.Clock();

function animate() {
  const elapsed = clock.getElapsedTime();

  // Orbit
  mesh.position.x = Math.cos(elapsed) * 3;
  mesh.position.z = Math.sin(elapsed) * 3;

  // Bob up and down
  mesh.position.y = Math.sin(elapsed * 2) * 0.5 + 1;

  // Continuous rotation
  mesh.rotation.y += 0.01;

  renderer.render(scene, camera);
}
renderer.setAnimationLoop(animate);

4.8 Loading 3D Models

GLTFLoader (Recommended Format)

glTF (.glb / .gltf) is the recommended format for three.js.

import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';

const dracoLoader = new DRACOLoader();
dracoLoader.setDecoderPath('https://www.gstatic.com/draco/versioned/decoders/1.5.7/');

const gltfLoader = new GLTFLoader();
gltfLoader.setDRACOLoader(dracoLoader);

gltfLoader.load(
  'model.glb',
  (gltf) => {
    const model = gltf.scene;
    scene.add(model);

    // Access animations
    console.log('Animations:', gltf.animations);

    // Access cameras embedded in the file
    console.log('Cameras:', gltf.cameras);
  },
  (xhr) => {
    console.log((xhr.loaded / xhr.total * 100) + '% loaded');
  },
  (error) => {
    console.error('Error loading model:', error);
  }
);

Other Loaders

import { OBJLoader } from 'three/addons/loaders/OBJLoader.js';
import { FBXLoader } from 'three/addons/loaders/FBXLoader.js';
import { STLLoader } from 'three/addons/loaders/STLLoader.js';
import { PLYLoader } from 'three/addons/loaders/PLYLoader.js';
import { PCDLoader } from 'three/addons/loaders/PCDLoader.js';
import { ColladaLoader } from 'three/addons/loaders/ColladaLoader.js';

// OBJ
const objLoader = new OBJLoader();
objLoader.load('model.obj', (obj) => scene.add(obj));

// FBX
const fbxLoader = new FBXLoader();
fbxLoader.load('model.fbx', (fbx) => {
  scene.add(fbx);
  // FBX animations
  if (fbx.animations.length > 0) {
    const mixer = new THREE.AnimationMixer(fbx);
    mixer.clipAction(fbx.animations[0]).play();
  }
});

// STL (3D printing format, geometry only)
const stlLoader = new STLLoader();
stlLoader.load('model.stl', (geometry) => {
  const mesh = new THREE.Mesh(geometry, new THREE.MeshStandardMaterial());
  scene.add(mesh);
});

KTX2Loader (Compressed Textures)

import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js';

const ktx2Loader = new KTX2Loader();
ktx2Loader.setTranscoderPath('https://unpkg.com/three@0.184.0/examples/jsm/libs/basis/');
ktx2Loader.detectSupport(renderer);

ktx2Loader.load('texture.ktx2', (texture) => {
  material.map = texture;
  material.needsUpdate = true;
});

4.9 Audio

three.js integrates the Web Audio API for 3D spatial audio.

// Listener attached to the camera
const listener = new THREE.AudioListener();
camera.add(listener);

// Non-positional (ambient) audio
const bgMusic = new THREE.Audio(listener);
const audioLoader = new THREE.AudioLoader();
audioLoader.load('music.mp3', (buffer) => {
  bgMusic.setBuffer(buffer);
  bgMusic.setLoop(true);
  bgMusic.setVolume(0.5);
  bgMusic.play();
});

// Positional (3D spatialized) audio
const sound = new THREE.PositionalAudio(listener);
audioLoader.load('engine.mp3', (buffer) => {
  sound.setBuffer(buffer);
  sound.setRefDistance(1);
  sound.setLoop(true);
  sound.play();
});
carMesh.add(sound); // attach to a mesh — sound follows the mesh in 3D space

// Audio analysis (frequency data)
const analyser = new THREE.AudioAnalyser(bgMusic, 256); // fftSize
// In animation loop:
const data = analyser.getAverageFrequency(); // returns 0-255

Note

Browsers require a user gesture (click, tap) before audio can play. Start audio playback inside a click event handler, not on page load.

4.10 Interaction and Raycasting

Raycaster

Raycaster projects a ray from one point in a direction and reports which objects it intersects.

const raycaster = new THREE.Raycaster();
const pointer = new THREE.Vector2();

window.addEventListener('click', (event) => {
  // Convert mouse position to normalized device coordinates (-1 to +1)
  pointer.x = (event.clientX / window.innerWidth) * 2 - 1;
  pointer.y = -(event.clientY / window.innerHeight) * 2 + 1;

  raycaster.setFromCamera(pointer, camera);

  const intersects = raycaster.intersectObjects(scene.children, true); // recursive

  if (intersects.length > 0) {
    const hit = intersects[0];
    console.log('Hit object:', hit.object.name);
    console.log('Hit point:', hit.point);          // Vector3 in world coords
    console.log('Hit face normal:', hit.face.normal); // face normal
    console.log('Distance:', hit.distance);

    // Highlight the clicked object
    hit.object.material.color.set(0xff0000);
  }
});

Using Layers for Selective Raycasting

// Set objects to specific layers
clickableObject.layers.set(1);      // only on layer 1
decorObject.layers.set(2);          // only on layer 2

// Raycaster respects its own layers setting
raycaster.layers.set(1);            // only test against layer-1 objects

OrbitControls

The most common way to let users navigate a 3D scene:

import { OrbitControls } from 'three/addons/controls/OrbitControls.js';

const controls = new OrbitControls(camera, renderer.domElement);
controls.enableDamping = true;       // smooth camera movement
controls.dampingFactor = 0.05;
controls.enableZoom = true;
controls.enablePan = true;
controls.enableRotate = true;
controls.minDistance = 2;            // min zoom
controls.maxDistance = 50;           // max zoom
controls.maxPolarAngle = Math.PI / 2; // prevent going below ground

// In animation loop:
controls.update();

Other available controls:

5. Common Tasks

5.1 Responsive Resize

Handle window resize to prevent stretching:

window.addEventListener('resize', () => {
  camera.aspect = window.innerWidth / window.innerHeight;
  camera.updateProjectionMatrix();
  renderer.setSize(window.innerWidth, window.innerHeight);
});

For OrthographicCamera:

window.addEventListener('resize', () => {
  const aspect = window.innerWidth / window.innerHeight;
  camera.left = -frustumSize * aspect / 2;
  camera.right = frustumSize * aspect / 2;
  camera.top = frustumSize / 2;
  camera.bottom = -frustumSize / 2;
  camera.updateProjectionMatrix();
  renderer.setSize(window.innerWidth, window.innerHeight);
});

5.2 Loading and Displaying a GLTF Model

Complete example with lighting, controls, and animation:

import * as THREE from 'three';
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';

const scene = new THREE.Scene();
scene.background = new THREE.Color(0xdddddd);

const camera = new THREE.PerspectiveCamera(45, window.innerWidth / window.innerHeight, 0.1, 100);
camera.position.set(0, 2, 5);

const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(window.innerWidth, window.innerHeight);
renderer.setPixelRatio(window.devicePixelRatio);
renderer.toneMapping = THREE.ACESFilmicToneMapping;
renderer.toneMappingExposure = 1.0;
renderer.outputColorSpace = THREE.SRGBColorSpace;
renderer.shadowMap.enabled = true;
document.body.appendChild(renderer.domElement);

// Lights
scene.add(new THREE.AmbientLight(0xffffff, 0.4));
const dirLight = new THREE.DirectionalLight(0xffffff, 1.5);
dirLight.position.set(5, 10, 5);
dirLight.castShadow = true;
dirLight.shadow.mapSize.set(2048, 2048);
scene.add(dirLight);

// Floor
const floor = new THREE.Mesh(
  new THREE.PlaneGeometry(20, 20),
  new THREE.MeshStandardMaterial({ color: 0x999999 })
);
floor.rotation.x = -Math.PI / 2;
floor.receiveShadow = true;
scene.add(floor);

// Controls
const controls = new OrbitControls(camera, renderer.domElement);
controls.enableDamping = true;

// Load model
let mixer;
const clock = new THREE.Clock();

const loader = new GLTFLoader();
loader.load('character.glb', (gltf) => {
  const model = gltf.scene;
  model.traverse((child) => {
    if (child.isMesh) {
      child.castShadow = true;
      child.receiveShadow = true;
    }
  });
  scene.add(model);

  // Play animations if present
  if (gltf.animations.length > 0) {
    mixer = new THREE.AnimationMixer(model);
    gltf.animations.forEach((clip) => {
      mixer.clipAction(clip).play();
    });
  }
});

// Render loop
function animate() {
  const delta = clock.getDelta();
  if (mixer) mixer.update(delta);
  controls.update();
  renderer.render(scene, camera);
}
renderer.setAnimationLoop(animate);

// Resize handling
window.addEventListener('resize', () => {
  camera.aspect = window.innerWidth / window.innerHeight;
  camera.updateProjectionMatrix();
  renderer.setSize(window.innerWidth, window.innerHeight);
});

5.3 Shadows

Complete shadow setup with multiple light types:

// Renderer
renderer.shadowMap.enabled = true;
renderer.shadowMap.type = THREE.PCFSoftShadowMap;

// Directional light shadows
const dirLight = new THREE.DirectionalLight(0xffffff, 1.5);
dirLight.position.set(10, 20, 10);
dirLight.castShadow = true;
dirLight.shadow.mapSize.set(2048, 2048);
dirLight.shadow.camera.near = 1;
dirLight.shadow.camera.far = 50;
dirLight.shadow.camera.left = -15;
dirLight.shadow.camera.right = 15;
dirLight.shadow.camera.top = 15;
dirLight.shadow.camera.bottom = -15;
dirLight.shadow.bias = -0.0001;
scene.add(dirLight);

// Spot light shadows
const spotLight = new THREE.SpotLight(0xffa500, 5);
spotLight.position.set(-5, 10, 0);
spotLight.angle = Math.PI / 6;
spotLight.penumbra = 0.3;
spotLight.castShadow = true;
spotLight.shadow.mapSize.set(1024, 1024);
scene.add(spotLight);
scene.add(spotLight.target);

// Objects: cast and receive
mesh.castShadow = true;
ground.receiveShadow = true;

5.4 Environment Maps and IBL

Use HDR environment maps for realistic lighting and reflections:

import { RGBELoader } from 'three/addons/loaders/RGBELoader.js';

const pmremGenerator = new THREE.PMREMGenerator(renderer);

new RGBELoader().load('environment.hdr', (hdrTexture) => {
  const envMap = pmremGenerator.fromEquirectangular(hdrTexture).texture;

  scene.background = envMap;       // visible background
  scene.environment = envMap;      // IBL for all PBR materials

  hdrTexture.dispose();
  pmremGenerator.dispose();
});

5.5 Instanced Rendering

Render many copies of the same geometry efficiently with InstancedMesh:

const count = 10000;
const geometry = new THREE.SphereGeometry(0.1, 16, 8);
const material = new THREE.MeshStandardMaterial({ color: 0xff8800 });
const instancedMesh = new THREE.InstancedMesh(geometry, material, count);

const dummy = new THREE.Object3D();
for (let i = 0; i < count; i++) {
  dummy.position.set(
    (Math.random() - 0.5) * 20,
    (Math.random() - 0.5) * 20,
    (Math.random() - 0.5) * 20
  );
  dummy.rotation.set(
    Math.random() * Math.PI,
    Math.random() * Math.PI,
    0
  );
  dummy.scale.setScalar(0.5 + Math.random());
  dummy.updateMatrix();
  instancedMesh.setMatrixAt(i, dummy.matrix);
}

instancedMesh.instanceMatrix.needsUpdate = true;
scene.add(instancedMesh);

For per-instance colors:

const color = new THREE.Color();
for (let i = 0; i < count; i++) {
  color.setHSL(Math.random(), 0.8, 0.5);
  instancedMesh.setColorAt(i, color);
}
instancedMesh.instanceColor.needsUpdate = true;

5.6 BatchedMesh (Dynamic Batching)

BatchedMesh allows combining different geometries into a single draw call with dynamic updates:

const batchedMesh = new THREE.BatchedMesh(
  100,      // max geometry count
  5000,     // max vertex count
  10000,    // max index count
  material
);

const boxGeoId = batchedMesh.addGeometry(new THREE.BoxGeometry(1, 1, 1));
const sphereGeoId = batchedMesh.addGeometry(new THREE.SphereGeometry(0.5, 16, 8));

// Add instances of those geometries
const inst1 = batchedMesh.addInstance(boxGeoId);
const inst2 = batchedMesh.addInstance(sphereGeoId);

const matrix = new THREE.Matrix4();
matrix.makeTranslation(2, 0, 0);
batchedMesh.setMatrixAt(inst1, matrix);

matrix.makeTranslation(-2, 0, 0);
batchedMesh.setMatrixAt(inst2, matrix);

scene.add(batchedMesh);

5.7 Post-Processing

Apply screen-space effects after rendering:

import { EffectComposer } from 'three/addons/postprocessing/EffectComposer.js';
import { RenderPass } from 'three/addons/postprocessing/RenderPass.js';
import { UnrealBloomPass } from 'three/addons/postprocessing/UnrealBloomPass.js';

const composer = new EffectComposer(renderer);
composer.addPass(new RenderPass(scene, camera));

const bloomPass = new UnrealBloomPass(
  new THREE.Vector2(window.innerWidth, window.innerHeight),
  1.5,   // strength
  0.4,   // radius
  0.85   // threshold
);
composer.addPass(bloomPass);

// Replace renderer.render() with:
function animate() {
  composer.render();
}
renderer.setAnimationLoop(animate);

The PostProcessing class (available with WebGPURenderer) provides a node-based alternative:

import * as THREE from 'three/webgpu';

const postProcessing = new THREE.PostProcessing(renderer);
// Configure passes via the node system

5.8 WebXR (VR/AR)

import { VRButton } from 'three/addons/webxr/VRButton.js';

renderer.xr.enabled = true;
document.body.appendChild(VRButton.createButton(renderer));

// Use setAnimationLoop — required for XR
renderer.setAnimationLoop((timestamp, frame) => {
  renderer.render(scene, camera);
});

Caution

WebXR is currently supported only with WebGLRenderer. Using WebGPURenderer with XR triggers: "THREE.XRManager: XR is currently not supported with a WebGPU backend. Use WebGL."

For AR:

import { ARButton } from 'three/addons/webxr/ARButton.js';

renderer.xr.enabled = true;
document.body.appendChild(ARButton.createButton(renderer));

5.9 Exporting Scenes

import { GLTFExporter } from 'three/addons/exporters/GLTFExporter.js';

const exporter = new GLTFExporter();

// Export as JSON (.gltf)
exporter.parse(
  scene,
  (result) => {
    const json = JSON.stringify(result, null, 2);
    downloadFile(json, 'scene.gltf', 'application/json');
  },
  (error) => { console.error(error); },
  { binary: false }
);

// Export as binary (.glb)
exporter.parse(
  scene,
  (result) => {
    downloadFile(result, 'scene.glb', 'application/octet-stream');
  },
  (error) => { console.error(error); },
  { binary: true }
);

Other exporters: OBJExporter, STLExporter, PLYExporter, USDZExporter.

5.10 Particles

Create particle systems with Points:

const particleCount = 5000;
const positions = new Float32Array(particleCount * 3);
const colors = new Float32Array(particleCount * 3);

for (let i = 0; i < particleCount; i++) {
  positions[i * 3] = (Math.random() - 0.5) * 20;
  positions[i * 3 + 1] = (Math.random() - 0.5) * 20;
  positions[i * 3 + 2] = (Math.random() - 0.5) * 20;

  colors[i * 3] = Math.random();
  colors[i * 3 + 1] = Math.random();
  colors[i * 3 + 2] = Math.random();
}

const geometry = new THREE.BufferGeometry();
geometry.setAttribute('position', new THREE.BufferAttribute(positions, 3));
geometry.setAttribute('color', new THREE.BufferAttribute(colors, 3));

const material = new THREE.PointsMaterial({
  size: 0.1,
  sizeAttenuation: true,
  vertexColors: true,         // use per-vertex colors
  transparent: true,
  alphaMap: particleTexture,
  depthWrite: false,          // prevent particles occluding each other
});

const particles = new THREE.Points(geometry, material);
scene.add(particles);