useGLTF

A composable to load GLTF models in TresJS scenes.

A composable that allows you to easily load glb/glTF models into your TresJS scene.

Usage

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

const path = './blender-cube.glb'
const { state, nodes, materials } = useGLTF(path)
</script>

<template>
  <primitive v-if="state" :object="state?.scene" />
</template>

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

<template>
  <TresCanvas clear-color="#F78B3D">
    <TresPerspectiveCamera :position="[3, 2, 5]" />
    <OrbitControls />
    <TheModel />
    <TresDirectionalLight
      :intensity="2"
      :position="[3, 3, 3]"
    />
    <TresAmbientLight :intensity="1" />
  </TresCanvas>
</template>

An advantage of using useGLTF is that you can pass a draco prop to enable Draco compression for the model. This will reduce the size of the model and improve performance.

import { useGLTF } from '@tresjs/cientos'

const { state, nodes, materials } = useGLTF('/models/AkuAku.gltf', { draco: true })

Return Values

Name	Type	Description
state	`Ref<GLTF \| null>`	The loaded GLTF, or `null` until it arrives
nodes	`ComputedRef<TNodes>`	All nodes in the scene, keyed by name
materials	`ComputedRef<TMaterials>`	All materials in the scene, keyed by name
isLoading	`Ref<boolean>`	Whether the model is currently loading
error	`Ref<unknown>`	Whatever the loader threw, if anything
progress	`{ loaded: number, total: number, percentage: number }`	Progress of the current load
load	`(path: string) => void`	Load a different model into the same state
execute	`(delay?: number) => Promise<GLTF>`	Re-run the load

Options

Name	Type	Default	Description
draco	`boolean`	`false`	Whether to enable Draco compression.
decoderPath	`string`	`'https://www.gstatic.com/draco/versioned/decoders/1.5.6/'`	Path to the Draco decoder.
traverse	`Function`		A traverse function applied to the scene upon loading the model.

Accessing Nodes and Materials

The composable provides computed properties to easily access nodes and materials in your scene:

const { nodes, materials } = useGLTF('/model.glb')

// Access a specific node
const mesh = nodes.value.MeshName

// Access a specific material
const material = materials.value.MaterialName

This makes it easier to manipulate specific parts of your model or apply materials programmatically.

Typing Nodes and Materials

The keys of nodes and materials come from the file, so by default both are a loose record and nodes.value.Body is an any. Pass the shape of your model as generics to get them typed:

import type { Mesh, MeshStandardMaterial } from 'three'
import { useGLTF } from '@tresjs/cientos'

interface ModelNodes { Body: Mesh }
interface ModelMaterials { Skin: MeshStandardMaterial }

const { nodes, materials } = useGLTF<ModelNodes, ModelMaterials>('/models/robot.glb')

nodes.value.Body.geometry // Mesh, not any

These interfaces are a claim about the model, not a proof: nothing checks them against the file at runtime. tres gltf reads them off the model and writes them for you, which is the only version of this that cannot drift.

Generating a Component Instead

For a whole model, writing an element per node by hand does not scale. The TresJS CLI generates that component from the model itself, typed, with a slot for every node so your overrides survive the next export:

npx @tresjs/cli gltf public/models/robot.glb
# ✔ src/models/Robot.gen.vue
#   3 slots: Head, Body, Base

The three ways to load a model, and when to reach for each one.

Loaders

Asset loading composables for TresJS scenes.

GLTFModel

A component based on useGLTF to load models in TresJS scenes.