OrbitControls
Learn how to use OrbitControls in TresJS, including both manual and plug-and-play approaches.
OrbitControls is a camera controller that allows you to orbit around a target. It's a great way to explore your scene interactively.
The OrbitControls utility, which allows users to easily navigate around a 3D scene, isn't included in the core Three.js library by default. To use it, you need to import it manually from the
three/addons/controls/OrbitControls module via the three-stdlib package. Alternatively, if you're using the TresJS ecosystem, you can opt for a ready-to-use version of OrbitControls available as a component in the @tresjs/cientos package.Using OrbitControls Manually
To use OrbitControls manually, import it and extend the catalog:
setup.ts
import { extend } from '@tresjs/core'
import { OrbitControls } from 'three/addons/controls/OrbitControls'
extend({ OrbitControls })
Now you can use the TresOrbitControls component in your scene. Since OrbitControls needs a reference to the camera and renderer, you can use the useTres composable:
<script setup lang="ts">
import { useTres } from '@tresjs/core'
const { camera, renderer } = useTres()
</script>
<template>
<TresOrbitControls
v-if="renderer"
:args="[camera, renderer?.domElement]"
/>
</template>
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import OrbitControls from './OrbitControls.vue'
</script>
<template>
<TresCanvas shadows alpha>
<TresPerspectiveCamera :args="[45, 1, 0.1, 1000]" />
<OrbitControls />
<TresGridHelper :args="[10, 10]" />
</TresCanvas>
</template>
OrbitControls from @tresjs/cientos (Recommended)
The @tresjs/cientos package provides a plug-and-play <OrbitControls /> component that wraps the ThreeJS OrbitControls. You don't need to extend the catalog or pass any arguments—it just works!
CientosOrbitControls.vue
<script setup lang="ts">
import { OrbitControls } from '@tresjs/cientos'
import { TresCanvas } from '@tresjs/core'
</script>
<template>
<TresCanvas shadows alpha>
<TresPerspectiveCamera :args="[45, 1, 0.1, 1000]" />
<OrbitControls />
</TresCanvas>
</template>
Make sure the
PerspectiveCamera is set first in the canvas, otherwise controls might not work as expected.