OrbitControls

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

However, it is not part of the core of ThreeJS. So to use it you would need to import it from the three/addons/controls/OrbitControls module.

This creates a problem because TresJS automatically creates a catalog of the core of Three so you can use them as components.

Fortunately, TresJS provides a way to extend the catalog of components. You can do it by using the extend method from the core library.

For more information about extending your TresJS catalog, refer to the extending section.

Using OrbitControls

To use OrbitControls you need to import it from the three/addons/controls/OrbitControls module.

import { OrbitControls } from 'three/addons/controls/OrbitControls'

Then you need to extend the catalogue of components using the extend method.

import { extend } from '@tresjs/core'
import { OrbitControls } from 'three/addons/controls/OrbitControls'

extend({ OrbitControls })

Now you can use the TresOrbitControls component in your scene.

OrbitControls.vue

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

Since OrbitControls needs a reference to the camera and the renderer. You need to pass those as arguments. You can use the useTresContext composable to get the camera and the renderer.

WARNING

useTresContext can be only be used inside of a TresCanvas since TresCanvas acts as the provider for the context data. Thats why we created a subcomponent called OrbitControls.vue. See more about context.

import { useTresContext } from '@tresjs/core'

const { camera, renderer } = useTresContext()

So the final code would be something like this:

OrbitControls.vue

<script setup lang="ts">
import { extend, useTresContext } from '@tresjs/core'
import { OrbitControls } from 'three/addons/controls/OrbitControls'

extend({ OrbitControls })

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

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

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>

OrbitControls from cientos

Here is where the fancy part begins. ✨ The cientos package provides a component called <OrbitControls /> which is a wrapper of the OrbitControls from the three-stdlib module.

The nicest part? You don't need to extend the catalog or pass any arguments. It just works. 💯

<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { OrbitControls } from '@tresjs/cientos'
</script>

<template>
  <TresCanvas
    shadows
    alpha
  >
    <TresPerspectiveCamera :args="[45, 1, 0.1, 1000]" />
    <OrbitControls />
  </TresCanvas>
</template>