@threlte/core

useLoader

A hook to load data with an arbitrary THREE loader class. The result of load is cached and subsequent calls will return the same result.

Instantiating A Loader

A loader must always be instantiated at the top level of a component. This is because the loader is depending on an application-wide cache:

<script>
  import { useLoader } from '@threlte/core'
  import { TextureLoader } from 'three'

  const loader = useLoader(TextureLoader)
</script>

A loader can be extended, to add custom features:

<script>
  import { useLoader } from '@threlte/core'
  import { TextureLoader } from 'three'

  const loader = useLoader(CustomTextureLoader, {
    extend: (loader) => {
      // do something with the loader, e.g. add DRACO support for
      // GLTFLoader or add custom headers for TextureLoader.
    }
  })
</script>

Loading An Asset

<script>
  import { useLoader } from '@threlte/core'
  import { TextureLoader } from 'three'

  const texture = useLoader(TextureLoader).load('path/to/texture.png')

  // A loader must always be instantiated at the top level of a component.
  const { load } = useLoader(TextureLoader)
  const onSomeEvent = () => {
    // To load an asset outside of the top level, use the `load` method.
    const texture = load('path/to/texture.png')
  }
</script>

The return type of load is a custom Threlte store called AsyncWritable and can be used as a regular Svelte store. Its initial value is undefined and will be updated once the asset is loaded.

The store also exposes the underlying promise methods then and catch and can therefore be directly awaited:

<script>
  import { useLoader, T } from '@threlte/core'
  import { TextureLoader } from 'three'

  const { load } = useLoader(TextureLoader)

  const onSomeEvent = async () => {
    // Load an asset and await the result.
    const texture = await load('path/to/texture.png')
  }
</script>

<!-- Or make use of Svelte's await block -->
{#await load('path/to/texture.png') then map}
  <T.MeshStandardMaterial {map} />
{/await}

Loading Multiple Assets

The function load of useLoader also accepts an array of paths in which case the return value is an array of loaded assets:

<script>
  import { useLoader } from '@threlte/core'
  import { TextureLoader } from 'three'

  const { load } = useLoader(TextureLoader)
  const textures = load(['texture1.png', 'texture2.png'])

  $: console.log($textures) // [Texture, Texture]
</script>

Keep in mind that the store will be updated and the promise resolves once all assets are loaded.

You can also provide a map of paths to load multiple assets at once. In this case the return value is a map of the loaded assets:

<script>
  import { useLoader } from '@threlte/core'
  import { TextureLoader } from 'three'

  const { load } = useLoader(TextureLoader)
  const textures = load({
    texture1: 'texture1.png',
    texture2: 'texture2.png'
  })

  $: console.log($textures) // { texture1: Texture, texture2: Texture }
</script>

Transforming The Result

Caching

The result of the transformation is cached and subsequent calls will return the same result.

The load method accepts an optional second argument to transform the result of the loader:

<script>
  import { useLoader } from '@threlte/core'
  import { TextureLoader } from 'three'

  const { load } = useLoader(TextureLoader)
  const texture = load('path/to/texture.png', {
    transform: (texture) => {
      // do something with the texture
      return texture
    }
  })
</script>

The return type of the transformation is used to infer the return type of the load method.

Previous PageuseRender

Next PageuseThrelteUserContext