Texture Loading

useTexture is an adapter runtime hook that loads textures from URLs, exposes reactive loading and both raw/normalized error state, and handles cancellation and resource cleanup automatically.

For texture declaration and configuration in materials, see Texture Definitions.

Basic usage

useTexture starts loading immediately when called. It returns reactive stores that update as the load progresses.

URL input forms

// Static
const tex = useTexture(['/assets/a.png', '/assets/b.png']);

// Dynamic
const tex = useTexture(() => [
  `/assets/textures/${currentSet}/diffuse.png`,
  `/assets/textures/${currentSet}/normal.png`
]);

// Static
const tex = useTexture(['/assets/a.png', '/assets/b.png']);

// Dynamic
const tex = useTexture(() => [
  `/assets/textures/${currentSet}/diffuse.png`,
  `/assets/textures/${currentSet}/normal.png`
]);

Return value (UseTextureResult)

Using .current for synchronous access

All stores expose a .current getter for zero-subscription reads — ideal for useFrame callbacks:

useFrame((state) => {
  if (loaded.loading.current) return; // Skip while loading
  if (loaded.error.current) return;   // Skip on error

  const textures = loaded.textures.current;
  if (textures) {
    state.setTexture('uDiffuse', { source: textures[0].source });
    state.setTexture('uNormal', { source: textures[1].source });
  }
});

useFrame((state) => {
  if (loaded.loading.current) return; // Skip while loading
  if (loaded.error.current) return;   // Skip on error

  const textures = loaded.textures.current;
  if (textures) {
    state.setTexture('uDiffuse', { source: textures[0].source });
    state.setTexture('uNormal', { source: textures[1].source });
  }
});

Using reactive subscriptions for UI

TextureLoadOptions

TextureDecodeOptions

Example with options

const loaded = useTexture(
  ['/assets/hdr-env.png'],
  {
    colorSpace: 'linear',
    generateMipmaps: true,
    decode: {
      premultiplyAlpha: 'none'
    }
  }
);

const loaded = useTexture(
  ['/assets/hdr-env.png'],
  {
    colorSpace: 'linear',
    generateMipmaps: true,
    decode: {
      premultiplyAlpha: 'none'
    }
  }
);

LoadedTexture shape

Each loaded texture provides:

Abort, reload, and race safety

useTexture is designed for safe async operation in a reactive environment:

Cancellation on reload

When reload() is called, any in-flight request is aborted before the new one starts. This prevents stale results from overwriting fresh data.

Request versioning

Each load increments an internal version counter. When a response arrives, it is only accepted if its version matches the current counter. This eliminates race conditions from overlapping loads.

Dispose on replacement

When new textures are loaded successfully, the previous bitmaps are disposed. When the component is destroyed, all current bitmaps are disposed.

Abort error suppression

AbortError exceptions are treated as expected cancellation and are not surfaced in the error or errorReport stores. Only genuine failures (network errors, decode errors, etc.) appear.

Blob cache

Under the hood, texture-loader.ts maintains a reference-counted blob cache. This means:

• If two useTexture calls request the same URL with the same options, only one network request is made.
• The cache key is deterministic: JSON.stringify({ url, colorSpace, requestInit, decode }).
• Entries are evicted when their reference count drops to zero (e.g., all components using that URL are destroyed).

Component lifecycle

useTexture performs adapter lifecycle cleanup automatically:

1. On destroy/unmount, disposed flag is set.
2. The internal requestVersion is incremented (invalidating any in-flight result).
3. The active AbortController is aborted.
4. All current bitmap textures are disposed.

This means you don’t need to manually clean up — the hook handles its own lifecycle.

Error handling