How to Load Animated GIF in React

To display an animated GIF in a React web app, use an <img> element with a local asset or hosted URL, or set the GIF as a CSS background. For a loading indicator, give the image useful alternative text and show it only while the related work is pending. Which asset syntax works depends on your project’s bundler and configuration.

Method 1: Importing GIFs Directly

Keep a GIF in the project when it belongs to the application and should be versioned with its code. In a project configured to import image assets, the import and component can be kept together as import loadingGif from './assets/loading.gif'; function LoadingGif({ loading }) { return loading ? <img src={loadingGif} alt="Loading results" width={48} height={48} /> : null; }. Replace ./assets/loading.gif with the path to your file. The component passes the imported asset value to src; asset imports are resolved by project tooling, and some setups instead use a public directory path. Check the build tool’s asset guidance if the import is not recognized. require() is another syntax some toolchains accept, but it is not a universal replacement for import and does not by itself configure GIF handling.

This plain JavaScript example shows the image details selected for a pending request:

const loading = true;
const loadingGif = { src: "/assets/loading.gif", alt: "Loading results" };
const image = loading ? loadingGif : null;

if (image) {
  console.log(`${image.src} | ${image.alt}`);
}

/assets/loading.gif | Loading results

Use the same loading condition in JSX to render the imported asset only while the request is pending.

Choose concise alt text that explains the image’s purpose. If the GIF is purely decorative beside text that already says “Loading,” use alt="" to avoid repeating the same information to screen-reader users. Give the image dimensions when known to reserve layout space. Large GIF files can delay loading and consume bandwidth, so reduce their dimensions and frame count or consider a suitable video or other animation format for the design.

Method 2: Using URLs for External GIFs

A hosted GIF can be used as an image source when you do not want to bundle the asset with the application. The URL below is an illustrative placeholder; replace it with a stable URL from a host you trust, then provide the same meaningful alternative text as for a local image:

<img src="https://example.com/loading.gif" alt="Loading results" width="48" height="48">

A complete component can use the hosted URL directly; replace the placeholder URL with your image’s address:

function ExternalGif() { return <img src="https://example.com/loading.gif" alt="Loading results" width={48} height={48} />; }

The browser requests the image from that host and displays it at the specified dimensions. Confirm that the host permits your site to display the image and that the URL will remain available. A third-party server can be slow, rate-limited, or unavailable; a CDN may help in some deployments, but it does not guarantee faster delivery. For a critical loading indicator, consider keeping a small local fallback or using a CSS spinner that does not depend on the remote image.

Method 3: CSS Background Images with GIFs

A CSS background is useful when the animation decorates a fixed-size region, such as a banner. This CSS rule and JSX element work together: the region is 320 pixels wide and 180 pixels high, while cover scales the GIF to fill it and may crop part of the image. center keeps the crop centered.

Use the same gif-background class in both places: CSS .gif-background { width: 320px; height: 180px; background-image: url('/assets/banner.gif'); background-size: cover; background-position: center; } and JSX <div className="gif-background" aria-hidden="true" />. The background displays the GIF as decoration inside that sized region. Background images have no img alternative-text attribute, so do not use this approach when the animation conveys information that is missing from nearby text. If text sits over the moving image, check contrast throughout the animation; a solid or translucent overlay can help keep the text readable. CSS background loading and asset URL handling also depend on the project’s build setup.

Conclusion

Use a local import for an asset maintained with the app, an external URL when a reliable host owns the image, and a CSS background for decoration behind a sized region. For a loading state, prioritize a small asset, descriptive status text, and an accessible fallback. Test the image URL and loading behavior in the configured application because bundlers and hosts handle assets differently.

FAQ

How can I show a placeholder while the GIF loads?

Track the image’s loading state with React state and handle the image’s onLoad and onError events. For example, import useState from React, then use function LoadingGif({ src }) { const [status, setStatus] = useState('loading'); return <>{status === 'loading' && <p role="status">Loading results</p>}{status === 'error' ? <p role="alert">The image could not be loaded.</p> : <img src={src} alt="" onLoad={() => setStatus('loaded')} onError={() => setStatus('error')} />}</>; }. Pass the imported asset or hosted URL as src. The status role gives the loading message status semantics, allowing assistive technology to announce this dynamic change politely. The text remains visible while the image is loading, disappears after onLoad, and is replaced by an error message after onError; the error keeps its alert behavior. If the GIF is decorative, the text can carry the status while the image uses empty alternative text.

How should I optimize a GIF?

Resize it to the largest dimensions it needs on screen and remove unnecessary frames. Compare the resulting file size and visual quality. Video or another animation format may be a better fit for long or detailed motion, but support and fallback needs depend on your target browsers and delivery setup.

Can React control GIF playback?

An animated GIF plays according to the frame and loop data stored in the file, so it may play once or repeat. An <img> element does not provide video-style play and pause controls. If users need playback controls, use a video element or an animation approach designed to expose those controls.