To integrate OrbitControls into your Three.js scene, you’ll first need to ensure that you’ve included the necessary scripts in your project. If you are using a module bundler like Webpack, you can import OrbitControls directly. Otherwise, you can grab it from the examples directory in the Three.js repository.
import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
Once you have that set up, create an instance of OrbitControls and link it to your camera and renderer’s DOM element. This will allow the controls to respond to user input, enabling smooth navigation around your 3D scene.
const controls = new OrbitControls(camera, renderer.domElement);
After creating the controls, you’ll want to configure some basic properties. For instance, you might want to set the minimum and maximum distance the camera can zoom in or out from the target. This can prevent the user from zooming through objects in your scene.
controls.minDistance = 5; controls.maxDistance = 100;
Additionally, you might want to limit the vertical rotation, preventing the camera from flipping upside down.
controls.maxPolarAngle = Math.PI / 2; // Limit vertical rotation
Don’t forget to call the update method on your controls within your animation loop. This ensures that any changes from user input are applied to the camera’s position and orientation during rendering.
function animate() {
requestAnimationFrame(animate);
controls.update(); // only required if controls.enableDamping = true, or if controls.autoRotate = true
renderer.render(scene, camera);
}
animate();
It’s also a good idea to set the controls to enable damping. This gives a more natural feel to the controls, as the camera movement will gradually come to a stop rather than halting abruptly.
controls.enableDamping = true; // an animation effect controls.dampingFactor = 0.25; // how quickly it stops
To add more polish, consider setting the target of the controls to focus on a particular object in your scene. This helps keep the user’s gaze centered on important elements as they navigate.
controls.target.set(0, 0, 0); // Set target to the origin or your object position controls.update(); // Update controls to apply the target setting
With these steps, you should have a solid foundation for using OrbitControls within your Three.js application. As you build out your scene, you can adjust properties like the zoom speed, rotation speed, and more to tailor the user experience.
Universal Remote Control XRT140 for VIZIO Smart TV Remote Replacement XRT136 XRT260 XRT270 Smartcast D, E, M, P, V, PX Series Smart TVs
$9.97 (as of June 2, 2026 22:39 GMT +00:00 - More infoProduct prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on [relevant Amazon Site(s), as applicable] at the time of purchase will apply to the purchase of this product.)Mastering the essential methods and properties of OrbitControls
OrbitControls exposes several methods and properties that let you fine-tune user interaction beyond the basics. For example, controls.enableZoom and controls.enableRotate let you selectively disable zooming or rotation if your scene requires it.
controls.enableZoom = false; // disables zooming controls.enableRotate = true; // enables rotation
In addition to zoom and rotation, you can control panning behavior. By default, panning is enabled and moves the camera’s target position. You can disable it with controls.enablePan, or adjust the speed via controls.panSpeed.
controls.enablePan = true; controls.panSpeed = 1.0; // default is 1.0, increase for faster panning
OrbitControls support different mouse buttons for different interactions. You can customize which mouse button triggers rotation, zoom, and pan by modifying controls.mouseButtons. That’s handy if you want to align controls with your app’s UX conventions.
controls.mouseButtons = {
LEFT: THREE.MOUSE.ROTATE,
MIDDLE: THREE.MOUSE.DOLLY,
RIGHT: THREE.MOUSE.PAN
};
Touch interactions are also configurable. You can enable or disable touch zoom and pan independently via controls.touches. For example, to disable pinch-to-zoom but keep panning on touch devices:
controls.touches = {
ONE: THREE.TOUCH.PAN,
TWO: THREE.TOUCH.DOLLY_ROTATE
};
The controls.autoRotate property allows the camera to automatically orbit around the target without user input. Adjust controls.autoRotateSpeed to control the rotation speed. This is useful for creating dynamic, continuously moving scenes.
controls.autoRotate = true; controls.autoRotateSpeed = 2.0; // radians per second
Another useful feature is controls.reset(), which resets the camera and controls back to their initial position and target. This can be triggered by a user action, such as clicking a “reset view” button.
button.addEventListener('click', () => {
controls.reset();
});
When dealing with complex scenes, you might want to restrict the camera’s azimuthal rotation (horizontal rotation) to prevent it from spinning endlessly. Use controls.minAzimuthAngle and controls.maxAzimuthAngle to clamp this rotation within a range.
controls.minAzimuthAngle = -Math.PI / 4; // -45 degrees controls.maxAzimuthAngle = Math.PI / 4; // 45 degrees
Since OrbitControls is event-driven, you can listen for control events like 'change', 'start', and 'end'. This allows you to react to user interaction, for example, to pause animations or update UI elements.
controls.addEventListener('change', () => {
console.log('Camera moved');
});
controls.addEventListener('start', () => {
console.log('User interaction started');
});
controls.addEventListener('end', () => {
console.log('User interaction ended');
});
To summarize the typical usage pattern: configure your properties upfront, call controls.update() inside your render loop when damping or auto-rotation is enabled, and listen for events to integrate with your app’s logic.
