@threlte/extras

useGltf

A Hook to load glTF files and use separate object nodes and materials of it.

Use the component <GLTF> if you want to use a model in its entirety.

Model: Battle Damaged Sci-fi Helmet by theblueturtle_

Examples

Basic Example

gltf is a store which gets populated as soon as the model loaded.

<script lang="ts">
  import { T } from '@threlte/core'
  import { useGltf } from '@threlte/extras'
  import { MeshBasicMaterial } from 'three'

  const gltf = useGltf('/path/to/model.glb')
</script>

<!-- Use an object node entirely -->
{#if $gltf}
  <T is={$gltf.nodes['node-name']} />
{/if}

<!-- or only the geometry -->
{#if $gltf}
  <T.Mesh
    geometry={$gltf.nodes['node-name'].geometry}
    material={new MeshBasicMaterial()}
  />
{/if}

DRACO decoding

Use a DRACO decoder for compressed glTF files, defaults to CDN loaded DRACO binaries.

import { useGltf } from '@threlte/extras'

const gltf = useGltf('/path/to/model.glb', {
  useDraco: true
})

You can set a custom path to DRACO decoder binaries.

import { useGltf } from '@threlte/extras'

const gltf = useGltf('/path/to/model.glb', {
  useDraco: '/custom/draco/decoders/path'
})

You can also provide your own instance of DRACOLoader

import { useGltf } from '@threlte/extras'

const myLoader = new DRACOLoader().setDecoderPath(path)

const gltf = useGltf('/path/to/model.glb', {
  useDraco: myLoader
})

Meshopt decoding

Use a meshopt decoder for compressed glTF files, defaults to Three’s included decoder.

import { useGltf } from '@threlte/extras'

const gltf = useGltf('/path/to/model.glb', {
  useMeshopt: true
})

Nodes and Materials

The hook provides a map of all objects and materials in the loaded glTF.

<script lang="ts">
  import { useGltf } from '@threlte/extras'

  const gltf = useGltf('/path/to/model.glb')
  $: nodes: $gltf?.nodes
  $: materials: $gltf?.materials
</script>

Provide types and you will gain autocompletion for these objects and materials.

<script lang="ts">
  import { useGltf } from '@threlte/extras'

  const gltf = useGltf<{
    nodes: {
      MeshA: THREE.Mesh
      MeshB: THREE.Mesh
      Object3DA: THREE.Object3D
    }
    materials: {
      MaterialA: THREE.MeshStandardMaterial
      MaterialB: THREE.MeshBasicMaterial
    }
  }>('/path/to/model.glb')

  $: if ($gltf) {
    const objectA = $gltf.nodes['MeshA'] // -> THREE.Mesh
    const materialA = $gltf.materials['MaterialA'] // -> THREE.MeshStandardMaterial
  }
</script>

How to get the types?

On the loading-assets page, Threlte provides the @threlte/gltf CLI tool that can be used to generate a reusable Svelte component for your gltf as well as its types.

Types can be separated into a typescript file and imported like so if you feel the need.

SomeGltf.ts

export type SomeGltf = {
  nodes: {
    Suzanne: THREE.Mesh
  }
  materials: {}
}

MyComponent.svelte

<script lang="ts">
  import { useGltf } from '@threlte/extras'
  import type { SomeGltf } from './SomeGltf.ts'

  useGltf<SomeGltf>('model.glb')
</script>

Previous Page Loading

Next Page useGltfAnimations