Skip to main content

<CanvasImage>v4.0.466

Renders a static image onto a <canvas> element.

Benefit: You can attach effects to the image.
Drawback: Assets must support CORS.
Use <Img> if you want a component based on the regular <img> tag.

MyComp.tsx
import {AbsoluteFill, CanvasImage, staticFile} from 'remotion';

export const MyComp: React.FC = () => {
  return (
    <AbsoluteFill>
      <CanvasImage src={staticFile('image.png')} />
    </AbsoluteFill>
  );
};

API​

src​

The URL of the image. Can be a remote URL or a local file path from staticFile().

Remote images need to support CORS because the image is drawn onto a canvas.

width?​

The canvas width in pixels.
If omitted, the decoded image width is used.

height?​

The canvas height in pixels.
If omitted, the decoded image height is used.

fit?​

Must be one of these values:

  • 'fill': The image will completely fill the canvas, and will be stretched if necessary. (default)
  • 'contain': The image is scaled to fit the canvas, while aspect ratio is maintained.
  • 'cover': The image completely fills the canvas and maintains its aspect ratio. It will be cropped if necessary.

effects?​

An array of Remotion effects to apply to the image after it has been drawn to the source canvas.

className?​

A class name to apply to the <canvas> element.

id?​

The HTML id attribute to apply to the <canvas> element.

style?​

Inline styles to apply to the <canvas> element.

onError?​

Called when the image cannot be loaded, decoded, or drawn after all retries are exhausted.
If omitted, cancelRender() is called.

pauseWhenLoading?v4.0.467​

If true, the Player will pause playback while the image is loading. Default false.
Has no effect during rendering (rendering always waits via delayRender()).

maxRetries?v4.0.467​

The number of times to retry loading the image after a failure before giving up. Default 2.
Retries use exponential backoff: the first retry waits 1 second, the second 2 seconds, the third 4 seconds, and so on.

delayRenderRetries?v4.0.467​

How many times delayRender() may retry before the render times out.
Passed directly to the retries option of delayRender().

delayRenderTimeoutInMilliseconds?v4.0.467​

The timeout in milliseconds for each delayRender() call.
Passed directly to the timeoutInMilliseconds option of delayRender().

Inherited props​

<CanvasImage> inherits from, durationInFrames, name, showInTimeline and hidden from <Sequence>.

Adding a ref​

You can add a React ref to a <CanvasImage> component.
If you use TypeScript, type it with HTMLCanvasElement:

MyComp.tsx
import {useRef} from 'react';
import {CanvasImage, staticFile} from 'remotion';

export const MyComp: React.FC = () => {
  const ref = useRef<HTMLCanvasElement>(null);

  return <CanvasImage ref={ref} src={staticFile('image.png')} />;
};

Compatibility​

BrowsersEnvironments
Chrome
Firefox
Safari

See also​