Constructor Arguments
Understanding Constructor Arguments
Many Three.js classes require arguments when instantiated. For example, creating a PerspectiveCamera in vanilla Three.js:
import { PerspectiveCamera } from 'three'
// Constructor: PerspectiveCamera(fov, aspect, near, far)
const camera = new PerspectiveCamera(45, 1, 0.1, 1000)
TresJS provides the args prop to pass these constructor arguments as an array.
The args Prop
The args prop accepts an array of constructor arguments that are passed directly to the Three.js constructor in order:
<template>
<TresCanvas>
<!-- Creates: new THREE.PerspectiveCamera(45, 1, 0.1, 1000) -->
<TresPerspectiveCamera :args="[45, 1, 0.1, 1000]" />
</TresCanvas>
</template>
Common Examples
Geometries
Geometries often require dimensional arguments:
<template>
<!-- BoxGeometry(width, height, depth) -->
<TresBoxGeometry :args="[2, 2, 2]" />
<!-- SphereGeometry(radius, widthSegments, heightSegments) -->
<TresSphereGeometry :args="[1, 32, 32]" />
<!-- PlaneGeometry(width, height, widthSegments, heightSegments) -->
<TresPlaneGeometry :args="[10, 10, 1, 1]" />
<!-- CylinderGeometry(radiusTop, radiusBottom, height, radialSegments) -->
<TresCylinderGeometry :args="[1, 1, 2, 32]" />
</template>
Cameras
<template>
<!-- PerspectiveCamera(fov, aspect, near, far) -->
<TresPerspectiveCamera :args="[75, 1, 0.1, 1000]" />
<!-- OrthographicCamera(left, right, top, bottom, near, far) -->
<TresOrthographicCamera :args="[-5, 5, 5, -5, 0.1, 1000]" />
</template>
Lights
<template>
<!-- DirectionalLight(color, intensity) -->
<TresDirectionalLight :args="['#ffffff', 1]" />
<!-- PointLight(color, intensity, distance, decay) -->
<TresPointLight :args="['#ff0000', 2, 100, 2]" />
<!-- SpotLight(color, intensity, distance, angle, penumbra, decay) -->
<TresSpotLight :args="['#ffffff', 1, 100, Math.PI / 6, 0.5, 2]" />
</template>
Materials with Options Object
Some constructors accept an options object as the first argument:
<template>
<!-- MeshBasicMaterial({ color, wireframe, ... }) -->
<TresMeshBasicMaterial :args="[{ color: 'red', wireframe: true }]" />
<!-- MeshStandardMaterial({ color, metalness, roughness, ... }) -->
<TresMeshStandardMaterial :args="[{ color: '#ff6b35', metalness: 0.5, roughness: 0.2 }]" />
</template>
args always expects an array.When to Use args vs Props
TresJS allows setting many properties declaratively via props. Use this rule of thumb:
Use args when... | Use props when... |
|---|---|
| Value is required at construction time | Value can be set after construction |
| Property is immutable after creation | Property is mutable |
| Creating geometries with dimensions | Setting position, rotation, scale |
| Setting material options at creation | Changing colors or values dynamically |
<template>
<!-- args for constructor, props for mutable properties -->
<TresMesh :position="[0, 1, 0]" :rotation="[0, Math.PI, 0]">
<TresBoxGeometry :args="[2, 2, 2]" />
<TresMeshStandardMaterial color="blue" />
</TresMesh>
</template>
Reactive Args
The args prop is reactive. When args changes, TresJS will recreate the Three.js instance with the new constructor arguments:
<script setup lang="ts">
const segments = ref(16)
</script>
<template>
<TresMesh>
<!-- Sphere is recreated when segments changes -->
<TresSphereGeometry :args="[1, segments, segments]" />
<TresMeshStandardMaterial />
</TresMesh>
<button @click="segments += 8">Increase Detail</button>
</template>
args.Key Takeaways
Array Format
args always accepts an array, even for single arguments or options objects.
Order Matters
Arguments must match the Three.js constructor signature exactly.
Reactivity
Changing args recreates the instance - use sparingly for performance.
Check the Docs
Reference Three.js documentation for constructor signatures.