Tres Components
Learn how TresJS automatically maps Vue components to Three.js objects using a custom renderer and autogenerated catalogue.
The Autogenerated Catalogue
TresJS provides an autogenerated catalogue of Vue components that map directly to Three.js classes. Any class exported from the three package is automatically available as a Vue component with the Tres prefix.
Naming Convention
| Vue Component | Three.js Class |
|---|---|
<TresPerspectiveCamera /> | new THREE.PerspectiveCamera() |
<TresMesh /> | new THREE.Mesh() |
<TresBoxGeometry /> | new THREE.BoxGeometry() |
<TresMeshBasicMaterial /> | new THREE.MeshBasicMaterial() |
<TresAmbientLight /> | new THREE.AmbientLight() |
No Imports Needed
Unlike vanilla Three.js where you must import each class:
import { PerspectiveCamera, Mesh, BoxGeometry } from 'three'
With TresJS, components are available automatically:
<template>
<TresCanvas>
<TresPerspectiveCamera :position="[5, 5, 5]" />
<TresMesh>
<TresBoxGeometry />
<TresMeshBasicMaterial color="red" />
</TresMesh>
</TresCanvas>
</template>
Since TresJS components map directly to Three.js classes, you can use the Three.js documentation as your API reference for constructor arguments and properties.
Working with Tres Components
TresJS components accept two types of configuration:
Constructor Arguments (args)
Pass arguments to the Three.js constructor using the args prop:
<template>
<!-- Creates: new THREE.BoxGeometry(2, 2, 2) -->
<TresBoxGeometry :args="[2, 2, 2]" />
<!-- Creates: new THREE.PerspectiveCamera(75, 1, 0.1, 1000) -->
<TresPerspectiveCamera :args="[75, 1, 0.1, 1000]" />
</template>
Declarative Properties
Set Three.js object properties using Vue props:
<script setup lang="ts">
const rotation = ref([0, Math.PI, 0])
const scale = ref(2)
</script>
<template>
<TresMesh
:position="[0, 1, 0]"
:rotation="rotation"
:scale
:cast-shadow="true"
>
<TresBoxGeometry />
<TresMeshStandardMaterial color="blue" :metalness="0.5" />
</TresMesh>
</template>
Extending the Catalogue
Add Three.js addons or custom classes using extend():
<script setup lang="ts">
import { extend } from '@tresjs/core'
import { OrbitControls } from 'three/addons/controls/OrbitControls'
extend({ OrbitControls })
</script>
<template>
<TresCanvas>
<TresPerspectiveCamera :position="[5, 5, 5]" />
<TresOrbitControls />
</TresCanvas>
</template>