Asset Hooks

PlayCanvas React provides hooks for loading and managing different assets. These hooks simplify the process of loading assets and allow you to handle loading and error states.

The general signature of every hook looks something like the following.

const { asset, loading, error } = useModel(src, props);

Where src is the URL of the asset and props are additional properties to pass to the asset loader.

import { useModel } from '@playcanvas/react/hooks';

export function RenderAsset() {
    const { asset, loading, error } = useModel('model.glb');

    if (loading) return <LoadingSpinner />;
    if (error) return <ErrorMessage message={error} />;
    if (!asset) return null;

    return <Render asset={asset} />;
}

Loading Progress

The useAsset hook supports loading progress via the subscribe callback. This is useful if you want to show a loading indicator or update a progress bar. Not all asset types return a progress value during load, so this is not guaranteed to be available for all asset types.

import { useSplat } from '@playcanvas/react/hooks';

export function RenderSplat() {
  const [progress, setProgress] = useState(0);
  const { asset, loading, error, subscribe } = useSplat('splat.ply');

  // Subscribe to loading progress
  useEffect(() => {
    const unsubscribe = subscribe(({ progress }) => setProgress(progress));
    return () => unsubscribe();
  }, [subscribe]);

  if (loading) return <LoadingSpinner />;
  if (error) return <ErrorMessage message={error} />;
  if (!asset) return null;

  return (<Entity>
    <GSplat asset={asset} />
  </Entity>);
}

All Hooks

The following hooks are available:

• useModel - Load a 3D model asset
• useSplat - Load a Gaussian Splat asset
• useTexture - Load a texture asset
• useEnvAtlas - Load an environment atlas texture
• useAsset - Generic hook for loading any type of asset

API

This is the full response of an asset hook.

Name	Type	Default
asset	Asset | null The loaded asset, or null if not loaded or failed	null
loading	boolean Whether the asset is currently loading, or false if it has loaded or failed	true
error	string | null Error message if loading failed, or null if successful	null
subscribe	(cb: AssetResultCallback) => () => void Use this to subscribe to loading progress events	-

useModel

A specialized hook for loading 3D model assets (GLB/GLTF). Pass the source URL of the model file and any additional properties to pass to the asset loader and use the resulting asset in the <Render/> component.

import { useModel } from '@playcanvas/react/hooks';

export function RenderModel() {
  const { asset, loading, error } = useModel('model.glb');

  if (loading) return <LoadingSpinner />;
  if (error) return <ErrorMessage message={error} />;
  if (!asset) return null;

  return <Render asset={asset} />;
}

Draco Decoding

The useModel hook also supports Draco decoding out of the box with zero configuration. @playcanvas/react will use the latest version of the Draco decoder (1.5.7) and lazy load it from the Google CDN.

Alternatively if you want to self-host the library you can manually configure the decoder using dracoInitialize.

import { dracoInitialize } from 'playcanvas';

dracoInitialize({
  jsUrl: '/draco_decoder.js',
  wasmUrl: '/draco_decoder.wasm',
  lazyInit: true
});

useSplat

A specialized hook for loading Gaussian Splat assets. Pass the source URL of the splat file and any additional properties to pass to the asset loader and use the resulting asset in the <GSplat/> component.

import { useSplat } from '@playcanvas/react/hooks';

export function RenderSplat() {
  const { asset, loading, error } = useSplat('splat.ply');
  if (loading) return <LoadingSpinner />;
  if (error) return <ErrorMessage message={error} />;
  if (!asset) return null;

  return (<Entity>
    <GSplat asset={asset} />
  </Entity>);
}

See the <GSplat/> component for more information.

useTexture

A specialized hook for loading texture assets. Pass the source URL of the texture file and any additional properties to pass to the asset loader and use the resulting asset in any component that accepts a texture.

import { useTexture } from '@playcanvas/react/hooks';
import { useMaterial } from '@playcanvas/react/hooks';

export function RenderTexture() {
  const { asset, loading, error } = useTexture('texture.jpg');
  const material = useMaterial({ map: asset.resource });

  if (loading) return <LoadingSpinner />;
  if (error) return <ErrorMessage message={error} />;
  if (!asset) return null;

  return <Render type="box" material={material} />;
}

See the useMaterial hook and Render component for more information.

useEnvAtlas

A specialized hook for loading environment atlas textures. Pass the source URL of the texture file and any additional properties to pass to the asset loader and use the resulting asset in the <Environment/> component.

import { useEnvAtlas } from '@playcanvas/react/hooks';
import { Environment } from '@playcanvas/react/components';

export function RenderEnvAtlas() {
  const { asset, loading, error } = useEnvAtlas('env.jpg');

  if (loading) return <LoadingSpinner />;
  if (error) return <ErrorMessage message={error} />;
  if (!asset) return null;

  return <Environment envAtlas={asset} />;
}

See the Environment component for more information.

useFont

Text in PlayCanvas is rendered using Signed-Distance-Fields (SDFs), so you'll need to convert your ttf fonts into the appropriate format before loading them.

If you're using Vite or Rollup there's an official plugin to convert ttf files for you at build time. Check out the @playcanvas/rollup for more information.

You can import a ttf using the ?sdf query parameter which will automatically convert it into an SDF texture at build time.

// Use the @playcanvas/rollup plugin to convert the ttf file into an SDF texture at build time.
import inconsolata from "@assets/fonts/inconsolata.ttf?sdf";
import { useFont } from '@playcanvas/react/hooks';

export function InconsolataFont() {
  const { asset, loading, error } = useFont(inconsolata);

  if (loading) return <LoadingSpinner />;
  if (error) return <ErrorMessage message={error} />;
  if (!asset) return null;

  return asset;
}

useAsset

This is a generic hook for loading any type of asset. You can use it to load any asset type that PlayCanvas supports which is sometimes useful if you need to load an asset dynamically.

import { useAsset } from '@playcanvas/react/hooks';

const assetTypeToLoadType = {
    'ply': useSplat,
    'jpg': useTexture,
    'png': useTexture,
    'glb': useModel,
    'gltf': useModel,
}

export function useDynamicAsset(src: string, props: Record<string, unknown> = {}) {

  const mimeType = src.split('.').pop();
  const loadType = assetTypeToLoadType[mimeType];

  if (!loadType) {
    throw new Error(`Unsupported asset type: ${mimeType}`);
  }

  return useAsset(src, loadType, props);
}