Asset Loading Configuration

Polotno provides methods to control how assets (images, fonts) are loaded, including timeout settings and error handlers.

Asset Load Timeout

Configure how long Polotno waits before timing out asset loads (images, SVGs). Default: 30 seconds. A load that fails is retried automatically — three attempts, with backoff — and those retries count against this timeout; a load that hangs is not retried, so the timeout is its only deadline.

import { setAssetLoadTimeout } from 'polotno/config';

// set timeout to 10 seconds
setAssetLoadTimeout(10000);

Font Load Timeout

Configure timeout specifically for font loading. Default: 6 seconds. A custom font whose file fails to download is fetched again (three attempts in total) within this budget; once the attempts are spent the font is reported as FONT_FAILED with reason: 'fetch-failed' instead of waiting out the timeout.

import { setFontLoadTimeout } from 'polotno/config';

// set font timeout to 15 seconds
setFontLoadTimeout(15000);

Error Handling

Register a global error handler for asset loading failures. The handler receives an Error with a code property and structured details, so you can react differently per failure type:

import { onLoadError } from 'polotno/config';

onLoadError((error) => {
  if (error.code === 'IMAGE_FAILED') {
    console.error(
      `Image failed to load (element ${error.details?.elementId}):`,
      error.message
    );
  } else if (error.code === 'FONT_FAILED') {
    console.error(`Font "${error.details?.family}" failed to load`);
  } else {
    console.error('Failed to load asset:', error.message);
  }
});

See Error Handling for the full list of codes and the details they carry. The same codes are reported when rendering through polotno-node.

Custom Image Loader (Advanced)

Advanced Feature: This is an experimental API for complex scenarios. Not supported in Cloud Render API or polotno-node.

Override the default image loading mechanism with a custom React hook. The hook must follow the react-konva useImage hook pattern, returning [image, status].

import React from 'react';
import { unstable_setImageLoaderHook } from 'polotno/config';

function useCustomImageLoader(url, crossOrigin) {
  const [image, setImage] = React.useState(null);
  const [status, setStatus] = React.useState('loading');

  React.useEffect(() => {
    if (!url) return;
    
    setStatus('loading');
    const img = document.createElement('img');
    
    const onLoad = () => {
      setStatus('loaded');
      setImage(img);
    };
    
    const onError = () => {
      setStatus('failed');
      setImage(null);
    };
    
    img.addEventListener('load', onLoad);
    img.addEventListener('error', onError);
    
    if (crossOrigin) {
      img.crossOrigin = crossOrigin;
    }
    img.src = url;
    
    return () => {
      img.removeEventListener('load', onLoad);
      img.removeEventListener('error', onError);
    };
  }, [url, crossOrigin]);
  
  return [image, status];
}

// register the custom hook
unstable_setImageLoaderHook(useCustomImageLoader);

Use Cases

Authentication: Modify URLs or add auth tokens before loading
S3 Link Revalidation: Refresh expired pre-signed URLs
Custom CDN Logic: Route requests through specific endpoints
Retry Logic: The default loader retries remote images (3 attempts, exponential backoff); a custom hook replaces it, so add your own retries if you want them

Asset Load Timeout

Font Load Timeout

Error Handling

Custom Image Loader (Advanced)

Use Cases

On this page