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

```ts [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](https://threejs.org/docs/#examples/en/controls/OrbitControls) needs a reference to the camera and renderer, you can use the `useTres` composable:

::code-group
```vue [OrbitControls.vue]
<script setup lang="ts">
import { useTres } from '@tresjs/core'

const { camera, renderer } = useTres()
</script>

<template>
  <TresOrbitControls
    v-if="renderer"
    :args="[camera, renderer?.domElement]"
  />
</template>
```

```vue [App.vue]
<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`](https://cientos.tresjs.org/) 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!

```vue [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>
```

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