Tresjs/docs/content/3.api/2.composables/1.use-tres.md

---

title: useTres

description: useTres provides a convenient access to a simplified TresJS context.

The useTres composable provides convenient access to a simplified TresJS context with direct access to core properties like the scene, renderer, camera, and utility functions. It's designed to be more straightforward than useTresContext while still providing access to essential TresJS functionality.

Usage

::warning useTres can only be used in child components of a TresCanvas component, as its data is provided by TresCanvas.

::

import { useTres } from '@tresjs/core'

const { scene, renderer, camera, sizes, invalidate, advance } = useTres()

// Access the active camera
console.log('Current camera:', camera.value)

// Get canvas dimensions
console.log('Canvas size:', sizes.width.value, sizes.height.value)

// Trigger a re-render in on-demand mode
invalidate()

Basic Example

::code-group

<script setup lang="ts">
import { useTres } from '@tresjs/core'
import { watchEffect } from 'vue'

const { camera, sizes, invalidate } = useTres()

// React to camera changes
watchEffect(() => {
  if (camera.value) {
    console.log('Camera position:', camera.value.position)
    // Invalidate when camera changes to trigger re-render
    invalidate()
  }
})

// React to size changes
watchEffect(() => {
  console.log(`Canvas resized to: ${sizes.width.value}x${sizes.height.value}`)
})
</script>

<template>
  <TresMesh>
    <TresBoxGeometry />
    <TresMeshNormalMaterial />
  </TresMesh>
</template>

<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import MyComponent from './MyComponent.vue'
</script>

<template>
  <TresCanvas>
    <MyComponent />
  </TresCanvas>
</template>

::

Extending the Catalogue

Use the extend function to add custom Three.js objects to the TresJS catalogue:

<script setup lang="ts">
import { useTres } from '@tresjs/core'
import { TextGeometry } from 'three/examples/jsm/geometries/TextGeometry'
import { FontLoader } from 'three/examples/jsm/loaders/FontLoader'

const { extend } = useTres()

// Extend TresJS with custom geometries
extend({ TextGeometry })

// Now you can use <TresTextGeometry> in your template
</script>

<template>
  <TresTextGeometry :args="['Hello TresJS!', { font: myFont, size: 1 }]" />
</template>

::read-more{to="/api/components/tres-objects#extending-the-catalogue"} ::

Manual Rendering Control

For precise control over when frames are rendered:

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

const { advance, invalidate } = useTres()

const handleUserInteraction = () => {
  // In manual render mode, advance one frame
  if (renderMode === 'manual') {
    advance()
  }
  // In on-demand mode, mark for re-render
  else if (renderMode === 'on-demand') {
    invalidate()
  }
}
</script>

Properties

The useTres composable returns an object with the following properties:

:::field-group ::::field{name="scene" type="ShallowRef"} The Three.js scene object containing all 3D objects in your scene. ::::

::::field{name="renderer" type="TresRenderer"} The Three.js WebGL renderer instance. Direct access to renderer methods and properties. ::::

::::field{name="camera" type="ComputedRef"} The currently active camera in the scene. Reactive reference that updates when the active camera changes. ::::

::::field{name="sizes" type="SizesType"} Reactive size information including canvas width, height, aspect ratio, and pixel ratio. ::::

::::field{name="controls" type="Ref"} Reference to the current camera controls instance (e.g., OrbitControls, FlyControls). ::::

::::field{name="extend" type="(objects: any) => void"} Function to extend the TresJS component catalogue with custom Three.js objects. ::::

::::field{name="events" type="EventManager"} The event manager instance for handling pointer interactions with 3D objects. ::::

::::field{name="invalidate" type="() => void"} Function to mark the scene as needing an update in the next frame. Essential for on-demand rendering mode. ::::

::::field{name="advance" type="() => void"} Function to manually advance the render loop by one frame. Required for manual rendering mode. :::: :::

Practical Examples

Responsive Camera Setup

<script setup lang="ts">
import { useTres } from '@tresjs/core'
import { watchEffect } from 'vue'

const { camera, sizes } = useTres()

// Update camera aspect ratio when canvas resizes
watchEffect(() => {
  if (camera.value && 'aspect' in camera.value) {
    camera.value.aspect = sizes.aspectRatio.value
    camera.value.updateProjectionMatrix()
  }
})
</script>

Custom Render Pipeline

<script setup lang="ts">
import { useTres } from '@tresjs/core'
import { EffectComposer } from 'three/examples/jsm/postprocessing/EffectComposer'

const { renderer, scene, camera } = useTres()

// Setup custom post-processing
const composer = new EffectComposer(renderer)
// Add your custom passes here

// Access to renderer for custom configuration
renderer.shadowMap.enabled = true
renderer.shadowMap.type = PCFSoftShadowMap
</script>

Dynamic Scene Management

<script setup lang="ts">
import { useTres } from '@tresjs/core'
import { BoxGeometry, Mesh, MeshBasicMaterial } from 'three'

const { scene, invalidate } = useTres()

const addDynamicObject = () => {
  const geometry = new BoxGeometry(1, 1, 1)
  const material = new MeshBasicMaterial({ color: 0x00FF00 })
  const cube = new Mesh(geometry, material)

  // Add directly to the scene
  scene.value.add(cube)

  // Trigger re-render in on-demand mode
  invalidate()
}
</script>

Difference from useTresContext

useTres provides a simplified interface compared to useTresContext:

Feature	useTres	useTresContext
Renderer	Direct TresRenderer instance	Renderer manager with additional methods
Camera	Active camera reference	Full camera management system
Complexity	Simplified, focused API	Complete context with all internal details
Use Case	Most common scenarios	Advanced use cases, internal operations

::tip Developer Tip: Choose useTres for typical 3D scene interactions, and useTresContext when you need access to the complete internal context. ::

Type

function useTres(): TresPartialContext

interface TresPartialContext {
  /** The Three.js scene object containing all 3D objects */
  scene: ShallowRef<TresScene>
  /** The Three.js WebGL renderer instance */
  renderer: TresRenderer
  /** The currently active camera */
  camera: ComputedRef<Camera | undefined>
  /** Reactive size information for the canvas */
  sizes: SizesType
  /** Reference to current camera controls */
  controls: Ref<TresControl | null>
  /** TresJS extension function for adding custom objects */
  extend: (objects: any) => void
  /** Event manager for pointer interactions */
  events: EventManager
  /** Mark scene for re-render in on-demand mode */
  invalidate: () => void
  /** Manually advance one frame in manual mode */
  advance: () => void
}

interface SizesType {
  /** Canvas width in pixels */
  width: Ref<number>
  /** Canvas height in pixels */
  height: Ref<number>
  /** Canvas aspect ratio (width / height) */
  aspectRatio: Ref<number>
  /** Device pixel ratio */
  pixelRatio: Ref<number>
}

type TresRenderer = WebGLRenderer | Renderer
type TresControl = any // Camera controls instance
type EventManager = any // Event manager instance