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.,
GLTFLoaderfor.glb/.gltf,FBXLoaderfor.fbx,TextureLoaderfor images). - Track loading progress using the
progressobject to show user feedback. - Use a
LoadingManagerfor global progress tracking across multiple assets. - Handle errors by watching the
errorref and providing fallback UI. - Reactive paths: You can pass a
refas 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.