Tresjs/docs/content/3.api/2.composables/5.use-loader.md

---

title: useLoader

description: 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

::examples-use-loader-texture ::

<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

::examples-use-loader-gltf ::

<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

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

:::field-group ::::field{name="state" type="Ref"} The loaded asset (model, texture, etc.), or null if not loaded yet. :::: ::::field{name="isLoading" type="Ref"} Indicates if the asset is currently loading. :::: ::::field{name="error" type="Ref"} Any error encountered during loading. :::: ::::field{name="progress" type="{ loaded: number; total: number; percentage: number }"} Progress information for the current load operation. :::: ::::field{name="load" type="(path: string) => void"} Method to load a new asset from a different path. :::: :::

Type 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.

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