packages/docs/docs/img.mdx
The tag can be used like a regular HTML tag.
If you use ``, 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.
srcPut an image into the public/ folder and use staticFile() to reference it.
import {AbsoluteFill, Img, staticFile} from 'remotion';
export const MyComp: React.FC = () => {
return (
<AbsoluteFill>
</AbsoluteFill>
);
};
You can also load a remote image:
import {AbsoluteFill, Img} from 'remotion';
export const MyComp: React.FC = () => {
return (
<AbsoluteFill>
</AbsoluteFill>
);
};
effects?<AvailableFrom v="4.0.469" />Apply effects to the image.
When effects is omitted or an empty array, renders a native element. When at least one effect is passed, `` renders through <CanvasImage> and outputs a <canvas>.
import {AbsoluteFill, Img, staticFile} from 'remotion';
import {blur} from '@remotion/effects/blur';
export const MyComp: React.FC = () => {
return (
<AbsoluteFill>
</AbsoluteFill>
);
};
Because the element becomes a <canvas>, native image props that require an `` element cannot be used with non-empty effects.
The unsupported props include ref, srcSet, sizes, loading, decoding, fetchPriority, useMap, crossOrigin, onLoad, onError, onImageFrame and alt.
Canvas-compatible props such as aria-*, data-*, role, title, tabIndex and pointer or mouse event handlers are forwarded to the underlying <canvas>.
When effects is a non-empty array, style.objectFit controls how the image is drawn into the canvas. Supported values are "fill", "contain" and "cover".
onErrorTo use the `` tag in a resilient way, handle the error that occurs when an image can not be loaded:
import {AbsoluteFill, Img, staticFile} from 'remotion';
export const MyComp: React.FC = () => {
return (
<AbsoluteFill>
{
// 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.
maxRetries<AvailableFrom v="3.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.
pauseWhenLoading?<AvailableFrom v="4.0.111"/>If set to true, pause the Player when the image is loading. See: Buffer state.
delayRenderTimeoutInMilliseconds?<AvailableFrom v="4.0.140" />Customize the timeout of the delayRender() call that this component makes.
delayRenderRetries?<AvailableFrom v="4.0.140" />Customize the number of retries of the delayRender() call that this component makes.
Prefer the maxRetries prop over this.
`` inherits from, durationInFrames, name, showInTimeline and hidden from <Sequence>.
:::note
You can still wrap `` in an outer <Sequence>. Timing cascades like nested sequences.
:::
import {AbsoluteFill, Img, staticFile} from 'remotion';
export const MyComp: React.FC = () => {
return (
<AbsoluteFill>
</AbsoluteFill>
);
};
Remotion inherits the props of the regular `` tag, like for example style. If effects is a non-empty array, only the props supported by <CanvasImage> are supported.
Don't use the `` tag for GIFs, use @remotion/gif instead.
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.
2^29 pixels (539 megapixels) <sup><a href="https://stackoverflow.com/questions/57223559/what-is-the-maximum-image-dimensions-supported-in-desktop-chrome#:~:text=than%202%5E29-,(539MP)">[source]</a></sup>. Remotion inherits this restriction.