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 the hooks is:


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

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

render-glb.tsx


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.

render-splat.tsx


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>);
}

API Reference

The useAsset hook has the following return type.

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

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

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 <Container/> component.

render-model.tsx


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 without 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.

render-draco.tsx


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.

render-splat.tsx


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, and the Gaussian Splat demo for a working example.

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.

render-texture.tsx


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.

render-env-atlas.tsx


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 EnvAtlas component for more information.

useFont

Text in PlayCanvas is rendered using Signed-Distance-Fields (SDF’s), 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 whhich will automatically convert it into an SDF texture at build time.

render-font.tsx


 
// 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.

use-dynamic-asset.tsx


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);
}