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

Every hooks returns an AssetResult with the following properties

Name	Type	Default
`asset`	`Asset \| null` The loaded asset, or null if not loaded or failed
`loading`	`boolean` Whether the asset is currently loading, or false if it has loaded or failed
`error`	`string \| null` Error message if loading failed, or null if successful

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

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

render-env-atlas.tsx


import { useEnvAtlas } from '@playcanvas/react/hooks';
 
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 <EnvAtlas asset={asset} />;
}

See the EnvAtlas component for more information.

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