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

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

::examples-use-loader-gltf
::

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

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

:::field-group
  ::::field{name="state" type="Ref<T | null>"}
  The loaded asset (model, texture, etc.), or `null` if not loaded yet.
  ::::
  ::::field{name="isLoading" type="Ref<boolean>"}
  Indicates if the asset is currently loading.
  ::::
  ::::field{name="error" type="Ref<unknown>"}
  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

```ts [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.
::