Get Started

Explore the 3D camera controls made simple. This documentation covers installation, configuration, and advanced usage patterns for Orbit Control.js.

🚀 Installation 🛠 Configuration 💡 Examples

📦 Installation


<$ npm install orbit-control.js
$ yarn add orbit-control.js
$ pnpm add orbit-control.js

We recommend installing via a package manager for the best performance. The package includes TypeScript definitions and browser-compatible builds.

Browser Support

Chrome, Firefox, Safari, Edge (90+), and modern mobile browsers. IE11 and older browsers require polyfills.

⚙️ Configuration

Basic Setup


import { OrbitControls } from 'orbit-control.js';
import * as THREE from 'three';

// Set up camera and scene
const camera = new THREE.PerspectiveCamera(75, window.innerWidth/window.innerHeight, 0.1, 1000);
const scene = new THREE.Scene();
const renderer = new THREE.WebGLRenderer();

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

// Common configuration
controls.enableDamping = true;
controls.dampingFactor = 0.05;
controls.zoomSpeed = 0.6;
controls.enablePan = true;
controls.minDistance = 10;
controls.maxDistance = 50;

The camera controls work with any Three.js scene. All configuration is done through the controls object.

Available Options

Camera Behavior

enableDamping boolean

dampingFactor number

zoomSpeed number

Movement Limits

minDistance / maxDistance number

minZoom / maxZoom number

minPolarAngle / maxPolarAngle radians

📚 Examples

Interactive 3D Viewer


import { OrbitControls } from 'orbit-control.js';

function createCameraControls() {
  const controls = new OrbitControls(camera, renderer.domElement);
  
  // Smooth damping
  controls.enableDamping = true;
  controls.dampingFactor = 0.05;
  
  // Distance limits
  controls.minDistance = 2;
  controls.maxDistance = 20;
  
  // Rotation limits
  controls.minAzimuthAngle = -Math.PI/2;
  controls.maxAzimuthAngle = Math.PI/2;
  
  return controls;
}

// On animation loop
function animate() {
  controls.update(); // Required only when damping is enabled
  renderer.render(scene, camera);
}

3D Viewer Preview

Zoom: 2-20 units | Rotation: -90° to 90°

Touch Support

Orbit Controls supports mobile and touch devices with natural gestures:

Pinch to Zoom

Pinching with two fingers zooms in/out. Double-tap to reset zoom.

Pan with Two Fingers

Swipe with two fingers at the same time to move the camera.

📚 API Reference

OrbitControls

Constructor

Creates a new instance linked to a camera and dom element.


const controls = new OrbitControls(camera, domElement);

update()

Updates the controls. Required for damping.

Usage: Should be called in your animation loop when damping is enabled

dispose()

Removes the camera controls.

Use this when you're done with the controls to clean up the connection to the camera.

Common Properties

enableDamping

Enables smooth inertial dragging. Recommended: true

dampingFactor

Controls how quickly damping slows the camera. 0.1 to 0.5 recommended

minDistance / maxDistance

Limits how far you can zoom out/in

rotateSpeed / zoomSpeed / panSpeed

Controls sensitivity of rotation, zoom, and panning

minAzimuthAngle / maxAzimuthAngle

Limits horizontal rotation (in radians)

minPolarAngle / maxPolarAngle

Limits vertical rotation (in radians)