Skip to main content

<Img>

The <Img> tag can be used like a regular <img> HTML tag.

If you use <Img>, Remotion will ensure that the image is loaded before rendering the frame. That way you can avoid flickers if the image does not load immediately during rendering.

API​

src​

Put an image into the public/ folder and use staticFile() to reference it.

tsx
import { AbsoluteFill, Img, staticFile } from "remotion";
 
export const MyComp: React.FC = () => {
  return (
    <AbsoluteFill>
      <Img src={staticFile("hi.png")} />
    </AbsoluteFill>
  );
};
tsx
import { AbsoluteFill, Img, staticFile } from "remotion";
 
export const MyComp: React.FC = () => {
  return (
    <AbsoluteFill>
      <Img src={staticFile("hi.png")} />
    </AbsoluteFill>
  );
};

You can also load a remote image:

tsx
import { AbsoluteFill, Img } from "remotion";
 
export const MyComp: React.FC = () => {
  return (
    <AbsoluteFill>
      <Img src={"https://picsum.photos/200/300"} />
    </AbsoluteFill>
  );
};
tsx
import { AbsoluteFill, Img } from "remotion";
 
export const MyComp: React.FC = () => {
  return (
    <AbsoluteFill>
      <Img src={"https://picsum.photos/200/300"} />
    </AbsoluteFill>
  );
};

onError​

To use the <Img> tag in a resilient way, handle the error that occurs when an image can not be loaded:

tsx
import { AbsoluteFill, Img, staticFile } from "remotion";
 
export const MyComp: React.FC = () => {
  return (
    <AbsoluteFill>
      <Img
        src={staticFile("hi.png")}
        onError={(event) => {
          // Handle image loading error here
        }}
      />
    </AbsoluteFill>
  );
};
tsx
import { AbsoluteFill, Img, staticFile } from "remotion";
 
export const MyComp: React.FC = () => {
  return (
    <AbsoluteFill>
      <Img
        src={staticFile("hi.png")}
        onError={(event) => {
          // Handle image loading error here
        }}
      />
    </AbsoluteFill>
  );
};

If an error occurs, the component must be unmounted or the src must be replaced, otherwise the render will time out.

From v3.3.82, the image load will first be retried before onError is thrown.

maxRetriesv3.3.82​

If an image fails to load, it will be retried from v3.3.82. The default value is 2.
An exponential backoff is being used, with 1000ms delay between the first and second attempt, then 2000ms, then 4000ms and so on.

pauseWhenLoadingv4.0.111​

optional

If set to true, pause the Player when the image is loading. See: Buffer state.

delayRenderTimeoutInMillisecondsv4.0.140​

Customize the timeout of the delayRender() call that this component makes.

delayRenderRetriesv4.0.140​

Customize the number of retries of the delayRender() call that this component makes.
Prefer the maxRetries prop over this.

Other props​

Remotion inherits the props of the regular <img> tag, like for example style.

GIFs​

Don't use the <Img> tag for GIFs, use @remotion/gif instead.

Error behavior​

From v4.0.0: If the image fails to load and no retries are left, then cancelRender will be called to throw an error, unless you handle the error using onError().

From v3.3.82: If an image fails to load, it will be retried up to two times.

In earlier versions, failing to load an image would lead to an error message in the console and an eventual timeout.

Restrictions​

  • The maximum resolution that Chrome can display is 2^29 pixels (539 megapixels) [source]. Remotion inherits this restriction.

See also​