Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 39 ยท Animation and Interaction

OrbitControls, TransformControls and Camera Rigs

Let users explore a Three.js scene with OrbitControls, move objects with TransformControls, choose between other controls, and build a smooth follow-camera rig by hand.

A scene the visitor cannot move around in feels like a picture. The easiest way to make it explorable is to attach controls to the camera: drag to rotate, scroll to zoom, right-drag to pan. Three.js ships a family of controls in its add-ons, and the one you will use most is OrbitControls. For editing scenes there is TransformControls, and for games you will usually write a small camera rig yourself.

This lesson covers the common controls, how to configure them, how to make them cooperate, and how to build a follow camera that moves smoothly.

OrbitControls

OrbitControls rotates the camera around a target point. Create it with the camera and the DOM element that receives events:

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

const controls = new OrbitControls(camera, renderer.domElement);
controls.enableDamping = true;     // inertia: smooth start and stop
controls.target.set(0, 1, 0);      // look-at point
controls.update();                 // required once after changing camera/target by hand

// in the animation loop (needed for damping and autoRotate)
controls.update();

Controls change the camera's position and rotation themselves, so do not also write to camera.position every frame (they will fight). To move the camera programmatically, change camera.position, then call controls.update(); to change where it looks, move controls.target.

Property Effect
enableDamping, dampingFactor Inertia (call update() each frame)
autoRotate, autoRotateSpeed Slow turntable, great for product displays
minDistance, maxDistance Zoom limits (perspective camera)
minPolarAngle, maxPolarAngle Vertical limits; Math.PI / 2 stops the camera going below the ground
minAzimuthAngle, maxAzimuthAngle Horizontal limits
enablePan, enableZoom, enableRotate Switch gestures off
screenSpacePanning Pan along the screen (true) or the ground plane (false)
mouseButtons, touches Remap buttons and gestures
keys and listenToKeyEvents(window) Arrow keys panning

The controls fire 'change', 'start' and 'end' events, which is how you render on demand: listen for change and redraw instead of drawing every frame.

OrbitControls with limits and auto-rotate

Drag the scene, scroll to zoom and try to look from under the floor: the polar limit stops you. getDistance(), getPolarAngle() and getAzimuthalAngle() read the camera's spherical position relative to the target, which is handy for UI that shows the current angle.

Choosing a control scheme

Control Use it for
OrbitControls Inspecting an object or a scene from outside; the default choice
MapControls Orbit variant with the mouse buttons swapped: drag pans, good for maps and city views
TrackballControls Free rotation with no fixed "up", for scientific or CAD-like viewers
ArcballControls Smooth arcball rotation with gizmo, pan, and focus
FlyControls Free flight, like a spectator camera
FirstPersonControls Simple first-person look and move
PointerLockControls Mouse capture for first-person games (needs a real page, not a sandboxed preview)
DragControls Drag objects with the mouse
TransformControls Move, rotate and scale gizmo for editors

All of these live in three/addons/controls/, and all need the camera plus a DOM element. Third-party packages such as camera-controls add smooth transitions (fitToBox, setLookAt with animation) that are very pleasant for product pages.

TransformControls: a gizmo for editing

TransformControls draws the familiar arrows (translate), rings (rotate) and boxes (scale) around an object and updates it as the user drags. Because both TransformControls and OrbitControls respond to the mouse, you must disable orbiting while the gizmo is being dragged, using the gizmo's dragging-changed event.

A transform gizmo that cooperates with OrbitControls

Without the dragging-changed line, dragging an arrow would also spin the camera. Note that getHelper() is the Object3D you add to the scene; older tutorials add the controls object itself, which no longer works in current versions.

Building a camera rig yourself

Games rarely use OrbitControls. A rig is a small hierarchy that separates responsibilities, for example a yaw group that turns left and right with a child pitch group that tilts up and down, and the camera inside. Because rotations are applied to different objects, you avoid the roll that creeps in when you rotate one object around two axes.

JavaScript
const yaw = new THREE.Group();
const pitch = new THREE.Group();
yaw.add(pitch);
pitch.add(camera);
scene.add(yaw);

// mouse or stick input:
yaw.rotation.y -= dx * 0.002;
pitch.rotation.x = THREE.MathUtils.clamp(pitch.rotation.x - dy * 0.002, -1.2, 1.2);

A follow camera chases a target with some lag. Compute where the camera wants to be (behind and above the target), then move toward it with the frame-rate independent damp from the animation lesson, and look at a point slightly ahead of the target.

A smooth follow camera

The lag between the car and the camera is what gives a feeling of speed. Raise the damping lambda (3) to stiffen the camera and lower it for a floatier view.

Common mistakes

  • Forgetting controls.update() in the loop when damping or auto-rotate is on, so the scene feels dead.
  • Moving camera.position every frame while controls are active.
  • Passing window or document instead of the canvas as the DOM element, which grabs events from the whole page (scrolling stops working).
  • Not calling controls.dispose() when tearing down a component, which leaves event listeners behind.
  • Setting touch-action: none on the canvas for touch devices, otherwise the browser scrolls instead of passing gestures to the controls.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which OrbitControls setting prevents the camera from going underneath the ground plane?

    The polar angle is measured from straight up. Limiting it to about 90 degrees keeps the camera at or above the horizon.
  2. 2. Why must you handle TransformControls' dragging-changed event?

    Both controls listen to the same pointer events. Setting orbit.enabled = !event.value gives the gizmo priority.
  3. 3. What must you do each frame when enableDamping is true?

    Damping continues the motion after you release the mouse, which only advances when update() is called each frame.
  4. 4. Why build a camera rig with separate yaw and pitch groups?

    Yaw on the parent and pitch on the child apply the rotations in a fixed order so the horizon stays level.

Summary

  • OrbitControls rotates, zooms and pans around a target; configure damping, limits and auto-rotate, and call update() each frame.
  • Other controls (Map, Trackball, Arcball, Fly, FirstPerson, PointerLock, Drag, Transform) cover different use cases.
  • TransformControls needs getHelper() in the scene and a dragging-changed handler to disable orbiting.
  • Camera rigs (yaw/pitch groups, damped follow cameras) give you full control in games.
  • Always target the canvas, set touch-action: none and dispose controls when finished.

Next: Shader Material Basics