You are reading Tres v1 docs. Head over tresjs.org for V2 docs.
Skip to content
On this page

Transform Controls

The Transform Controls are a set of three gizmos that can be used to translate, rotate and scale objects in the scene. It adapts a similar interaction model of DCC tools like Blender

Loading...

Usage

To use the Transform Controls, simply add the TransformControls component to your scene. You can pass the templateRefof the instance you want to control as a prop.

vue
<script setup>
const boxRef = shallowRef()
</script>
<template>
  <TresCanvas>
    <OrbitControls make-default />
    <TresScene>
        <TransformControls :object="boxRef" />
        <TresMesh ref="boxRef" :position="[0, 4, 0]" cast-shadow>
            <TresBoxGeometry :args="[1.5, 1.5, 1.5]" />
            <TresMeshToonMaterial color="#4F4F4F" />
        </TresMesh>
    </TresScene>
  </TresCanvas>
</template>

WARNING

If you are using other controls (OrbitControls) they will interfere with each other when dragging. To avoid this, you can set the makeDefault prop to true on the OrbitControls.

Modes

The Transform Controls can be used in three different modes:

Translate

Translate

The default mode allows you to move the object around the scene.

html
<TransformControls mode="translate" :object="sphereRef" />

Rotate

Rotate

The rotate mode allows you to rotate the object around the scene.

html
<TransformControls mode="rotate" :object="boxRef" />

Scale

Scale

The scale mode allows you to scale the object around the scene.

html
<TransformControls mode="scale" :object="sphereRef" />

Props

PropDescriptionDefault
objectThe instance Object3D to control.null
modeThe mode of the controls. Can be translate, rotate or scale.translate
enabledIf true, the controls will be enabled.true
axisThe axis to use for the controls. Can be X, Y, Z, XY, YZ, XZ, XYZ.XYZ
spaceThe space to use for the controls. Can be local or world.local
sizeThe size of the controls.1
translationSnapThe distance to snap to when translating. (World units)null
rotationSnapThe angle to snap to when rotating. (Radians)null
scaleSnapThe scale to snap to when scaling.null
showXIf true, the X-axis helper will be shown.true
showYIf true, the Y-axis helper will be shown.true
showZIf true, the Z-axis helper will be shown.true

Events

EventDescription
draggingFired when the user starts or stops dragging the controls.
changeFired when the user changes the controls.
mouseDownFired when the user clicks on the controls.
mouseUpFired when the user releases the mouse button on the controls.
objectChangeFired when the user changes the object.