---
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`](/api/components/tres-canvas) component, as its data is provided by [`TresCanvas`](/api/components/tres-canvas).

::

```ts
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

```vue [MyComponent.vue]
<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>
```

```vue [App.vue]
<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:

```vue
<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:

```vue
<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<TresScene>"}
  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<Camera | undefined>"}
  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<TresControl | null>"}
  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

```vue
<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

```vue
<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

```vue
<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

```ts [Signature]
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
```