Orbit controls

오빗 컨트롤

The most basic 3D-viewer camera rig: drag to orbit around a target, scroll to zoom.

Also known as: OrbitControlsCamera orbitDamping
···
js
import * as THREE from 'three';
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setPixelRatio(Math.min(devicePixelRatio, 2));
document.body.appendChild(renderer.domElement);
const scene = new THREE.Scene();
scene.background = new THREE.Color(0x0c0c16);
const camera = new THREE.PerspectiveCamera(45, 1, 0.1, 100);
camera.position.set(3.2, 2, 4.2);

scene.add(new THREE.AmbientLight(0x556080, 1.2));
const dLight = new THREE.DirectionalLight(0xffffff, 1.1);
dLight.position.set(4, 6, 3);
scene.add(dLight);

const mesh = new THREE.Mesh(
  new THREE.TorusKnotGeometry(1, 0.3, 140, 20),
  new THREE.MeshStandardMaterial({ color: 0x8f7bff, roughness: 0.35, metalness: 0.3 })
);
scene.add(mesh);

const controls = new OrbitControls(camera, renderer.domElement);
controls.enableDamping = true;
controls.autoRotate = true;
controls.autoRotateSpeed = 1.4;
controls.minDistance = 3;
controls.maxDistance = 9;

function resize() { renderer.setSize(innerWidth, innerHeight); camera.aspect = innerWidth / innerHeight; camera.updateProjectionMatrix(); }
addEventListener('resize', resize); resize();
renderer.setAnimationLoop(() => {
  controls.update();
  renderer.render(scene, camera);
});

OrbitControls(camera, domElement) treats the camera itself as spherical coordinates (azimuth, polar angle, distance) around a target point, translating pointer drags into angle changes and scroll into distance changes. You must call controls.update() every frame for the camera position to actually refresh.

Turn on enableDamping and the camera coasts to a stop like it has inertia after you let go, which feels much smoother. autoRotate plus autoRotateSpeed keeps the camera slowly orbiting on its own even without input — that’s why this demo keeps moving in the card preview too. minDistance/maxDistance stop the zoom from going too close or too far.

Internally it only ever changes the camera’s position and always keeps it looking at target, so you never touch camera.rotation directly.

When to use

Product 3D viewers, model previewers — anywhere the user needs to freely look an object over.