useLoader

useLoader is a composable for loading 3D assets and textures with Three.js loaders, supporting progress tracking and reactivity.

The useLoader composable provides a reactive and easy-to-use method for loading 3D models and textures with any Three.js loader. It supports progress tracking, error handling, and works seamlessly with Vue's reactivity system. This makes it ideal for loading assets in TresJS scenes, including GLTF, FBX, textures, and more.

Usage

Loading a Texture and Applying to a Mesh

TextureExample.vue

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

// Load a texture from a remote URL
const { state: texture, isLoading, error } = useLoader(
  TextureLoader,
  'https://raw.githubusercontent.com/Tresjs/assets/main/textures/black-rock/Rock035_2K_Color.jpg',
)
</script>

<template>
  <TresMesh>
    <TresBoxGeometry />
    <!-- Use the loaded texture as the material map -->
    <TresMeshStandardMaterial v-if="texture" :map="texture" />
  </TresMesh>
</template>

Loading a GLTF Model and Rendering a Named Node

GLTFExample.vue

<script setup lang="ts">
import { useGraph, useLoader } from '@tresjs/core'
import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js'
import { DRACOLoader } from 'three/examples/jsm/loaders/DRACOLoader.js'
import { computed } from 'vue'

// Setup DRACO loader for compressed GLTFs
const dracoLoader = new DRACOLoader()
dracoLoader.setDecoderPath('https://www.gstatic.com/draco/versioned/decoders/1.5.6/')

// Load a GLTF model
const { state: model, isLoading, error } = useLoader(
  GLTFLoader,
  'https://raw.githubusercontent.com/Tresjs/assets/main/models/gltf/blender-cube.glb',
  {
    extensions: (loader) => {
      if (loader instanceof GLTFLoader) {
        loader.setDRACOLoader(dracoLoader)
      }
    },
  },
)

// Extract the scene and graph
const scene = computed(() => model.value?.scene)
const graph = useGraph(scene)

const nodes = computed(() => graph.value.nodes)
</script>

<template>
  <!-- Render the Cube node if it exists -->
  <primitive
    v-if="nodes?.BlenderCube"
    :object="nodes?.BlenderCube"
  />
</template>

Loading an FBX Model and Rendering It

FBXExample.vue

<script setup lang="ts">
import { useLoader } from '@tresjs/core'
import { FBXLoader } from 'three/examples/jsm/loaders/FBXLoader.js'

// Load an FBX model
const { state: model, isLoading, error } = useLoader(
  FBXLoader,
  'https://raw.githubusercontent.com/Tresjs/assets/main/models/fbx/low-poly-truck/Jeep_done.fbx',
)
</script>

<template>
  <!-- Render the loaded FBX model -->
  <primitive v-if="model" :object="model" :scale="0.01" />
</template>

API

The useLoader composable returns a reactive object with the following properties:

state

Ref<T | null>

The loaded asset (model, texture, etc.), or null if not loaded yet.

isLoading

Ref<boolean>

Indicates if the asset is currently loading.

error

Ref<unknown>

Any error encountered during loading.

progress

{ loaded: number; total: number; percentage: number }

Progress information for the current load operation.

load

(path: string) => void

Method to load a new asset from a different path.

Type Signature

Signature

function useLoader<T, Shallow extends boolean = false>(
  Loader: LoaderProto<T>,
  path: MaybeRef<string>,
  options?: TresLoaderOptions<T, Shallow>,
): UseLoaderReturn<T, Shallow>

Tips & Best Practices

Always use the correct loader for your asset type (e.g., GLTFLoader for .glb/.gltf, FBXLoader for .fbx, TextureLoader for images).
Track loading progress using the progress object to show user feedback.
Use a LoadingManager for global progress tracking across multiple assets.
Handle errors by watching the error ref and providing fallback UI.
Reactive paths: You can pass a ref as the path to automatically reload when the path changes.

If you need to load multiple assets at once, create multiple useLoader instances or use a LoadingManager to coordinate progress.

useGraph

useGraph generates a reactive map of named nodes, materials, and meshes from a Three.js object hierarchy.

Pointer Events

Explore the TresJS pointer events system powered by @pmndrs/pointer-events.