Tresjs/docs/content/4.cookbook/1.orbit-controls.md

---

title: OrbitControls description: Learn how to use OrbitControls in TresJS, including both manual and plug-and-play approaches.

thumbnail: /recipes/orbit-controls.png

::examples-orbit-controls ::

OrbitControls is a camera controller that allows you to orbit around a target. It's a great way to explore your scene interactively.

::note 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:

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:

::code-group

<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>

::

::read-more{to="/api/components/tres-objects#extending-the-catalogue"} ::

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!

<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>

::tip Make sure the PerspectiveCamera is set first in the canvas, otherwise controls might not work as expected. ::