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 {CanvasImage, staticFile} from 'remotion';

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

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.

effects?​

An array of Remotion effects to apply to the image after it has been drawn to the source 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.

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.

crossOrigin?v4.0.526​

Controls the CORS mode used by the internal image loader. Supports "anonymous" and "use-credentials". Defaults to "anonymous".

cropLeft?v4.0.500​

Crops the canvas from the left by a ratio between 0 and 1. See cropLeft.

cropRight?v4.0.500​

Crops the canvas from the right by a ratio between 0 and 1. See cropRight.

cropTop?v4.0.500​

Crops the canvas from the top by a ratio between 0 and 1. See cropTop.

cropBottom?v4.0.500​

Crops the canvas from the bottom by a ratio between 0 and 1. See cropBottom.

premountFor?v4.0.495​

Mounts the canvas for the specified number of frames before its from frame. The canvas carries display: none and is frozen at its first frame while premounted.

Use this prop to let the image load, decode, and prepare its effects before it becomes visible. See Premounting.

postmountFor?v4.0.495​

Keeps the canvas mounted for the specified number of frames after its duration has ended. The canvas is invisible and frozen at its final frame while postmounted.

styleWhilePremounted?v4.0.495​

CSS styles applied to the canvas while it is premounted. These styles override the default display: none and pointer-events: none styles.

styleWhilePostmounted?v4.0.495​

CSS styles applied to the canvas while it is postmounted. These styles override the default display: none and pointer-events: none styles.

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, trimBeforev4.0.482, 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​