Threejs Syntax Controls

threejs-syntax-controls

Quick Reference

Control Selection Decision Tree

Import Paths (Three.js r160+)

import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
import { MapControls } from 'three/addons/controls/MapControls.js';
import { FlyControls } from 'three/addons/controls/FlyControls.js';
import { FirstPersonControls } from 'three/addons/controls/FirstPersonControls.js';
import { PointerLockControls } from 'three/addons/controls/PointerLockControls.js';
import { TransformControls } from 'three/addons/controls/TransformControls.js';
import { TrackballControls } from 'three/addons/controls/TrackballControls.js';
import { ArcballControls } from 'three/addons/controls/ArcballControls.js';
import { DragControls } from 'three/addons/controls/DragControls.js';

ALWAYS use 'three/addons/controls/...' for r160+. The legacy path 'three/examples/jsm/controls/...' still works but is deprecated.

Critical Warnings

ALWAYS call controls.update() in the animation loop when enableDamping or autoRotate is true. Failing to do so causes the camera to freeze after user interaction ends.

ALWAYS call controls.dispose() when removing controls. Failing to do so leaks DOM event listeners (pointermove, wheel, keydown) that cause memory leaks and ghost interactions.

NEVER attach two camera-control classes to the same camera simultaneously without disabling one. OrbitControls + FlyControls on the same camera causes erratic movement.

ALWAYS disable OrbitControls while TransformControls is dragging. Listen to the dragging-changed event and toggle orbitControls.enabled.

ALWAYS call PointerLockControls.lock() from a user gesture (click handler). Browsers reject pointer lock requests without user interaction.

ALWAYS pass delta time to FlyControls.update(delta). Passing no argument or passing elapsed time causes speed to depend on frame rate.

Controls Lifecycle

Every control follows the same lifecycle pattern:

construct --> configure --> attach to loop --> dispose on cleanup

Step 1: Construct

const controls = new OrbitControls(camera, renderer.domElement);

ALWAYS pass renderer.domElement as the second argument. Passing document or document.body causes controls to capture events globally, breaking UI overlays.

Step 2: Configure

controls.enableDamping = true;
controls.dampingFactor = 0.05;
controls.minDistance = 2;
controls.maxDistance = 50;
controls.target.set(0, 1, 0);

Step 3: Update in Render Loop

function animate() {
  requestAnimationFrame(animate);
  controls.update(); // REQUIRED when enableDamping or autoRotate is true
  renderer.render(scene, camera);
}
animate();

Step 4: Dispose on Cleanup

controls.dispose();

OrbitControls

The most commonly used control. Orbits, pans, and zooms around a target point.

Constructor

new OrbitControls(camera: THREE.Camera, domElement: HTMLElement)

Key Properties

Methods

Events

MapControls

Subclass of OrbitControls optimized for top-down map navigation.

All properties, methods, and events are identical to OrbitControls. The ONLY differences are the default mouseButtons mapping and screenSpacePanning defaulting to true.

FlyControls

Six-degrees-of-freedom flight camera. WASD for movement, QE for roll, RF for up/down.

Key Properties

Methods

• update(delta) -- ALWAYS pass delta time from the clock. NEVER omit this argument.
• dispose() -- Remove event listeners.

PointerLockControls

First-person camera using the Pointer Lock API. Hides and captures the mouse cursor.

Key Properties

Methods

Events

ALWAYS implement your own WASD movement in the animation loop. PointerLockControls handles look direction only, NOT position.

TransformControls

Interactive gizmo for moving, rotating, and scaling scene objects.

Key Properties

Methods

Events

Critical Integration Pattern

ALWAYS disable camera controls during gizmo drag:

transformControls.addEventListener('dragging-changed', (event) => {
  orbitControls.enabled = !event.value;
});

ALWAYS add TransformControls to the scene: scene.add(transformControls.getHelper()) or scene.add(transformControls).

Brief Overview: Other Controls

ArcballControls

Unconstrained rotation with animation states. No polar angle limit -- the camera rotates freely in all directions. Best for CAD-style model inspection.

TrackballControls

Like OrbitControls without the polar angle constraint. The camera can rotate past the poles. Properties: rotateSpeed, zoomSpeed, panSpeed, staticMoving, dynamicDampingFactor.

DragControls

Drag scene objects along a plane. Constructor: new DragControls(objects, camera, domElement). Events: dragstart, drag, dragend, hoveron, hoveroff.

FirstPersonControls

Mouse-look camera without pointer lock. Properties: movementSpeed, lookSpeed, activeLook, constrainVertical, verticalMin, verticalMax.

Reference Links

• references/methods.md -- Full API signatures for all controls
• references/examples.md -- Working code examples for each control type
• references/anti-patterns.md -- What NOT to do

Official Sources

• https://threejs.org/docs/#examples/en/controls/OrbitControls
• https://threejs.org/docs/#examples/en/controls/MapControls
• https://threejs.org/docs/#examples/en/controls/FlyControls
• https://threejs.org/docs/#examples/en/controls/PointerLockControls
• https://threejs.org/docs/#examples/en/controls/TransformControls