<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 constMyComp :React .FC = () => {return (<AbsoluteFill ><Img src ={staticFile ("hi.png")} /></AbsoluteFill >);};
tsx
import {AbsoluteFill ,Img ,staticFile } from "remotion";export constMyComp :React .FC = () => {return (<AbsoluteFill ><Img src ={staticFile ("hi.png")} /></AbsoluteFill >);};
You can also load a remote image:
tsx
import {AbsoluteFill ,Img } from "remotion";export constMyComp :React .FC = () => {return (<AbsoluteFill ><Img src ={"https://picsum.photos/200/300"} /></AbsoluteFill >);};
tsx
import {AbsoluteFill ,Img } from "remotion";export constMyComp :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 constMyComp :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 constMyComp :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.
maxRetries
v3.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.
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.