Light Dark System
Get ready for more awesome! Web Awesome, the next iteration of Shoelace, is on Kickstarter. Read Our Story

Animated Image

<sl-animated-image> | SlAnimatedImage
Since 2.0 stable

A component for displaying animated GIFs and WEBPs that play and pause on interaction. 

<sl-animated-image
  src="https://shoelace.style/assets/images/walk.gif"
  alt="Animation of untied shoes walking on pavement"
></sl-animated-image>

import SlAnimatedImage from '@shoelace-style/shoelace/dist/react/animated-image';

const App = () => (
  <SlAnimatedImage
    src="https://shoelace.style/assets/images/walk.gif"
    alt="Animation of untied shoes walking on pavement"
  />
);

Examples

WEBP Images

Both GIF and WEBP images are supported.

<sl-animated-image
  src="https://shoelace.style/assets/images/tie.webp"
  alt="Animation of a shoe being tied"
></sl-animated-image>

import SlAnimatedImage from '@shoelace-style/shoelace/dist/react/animated-image';

const App = () => (
  <SlAnimatedImage src="https://shoelace.style/assets/images/tie.webp" alt="Animation of a shoe being tied" />
);

Setting a Width and Height

To set a custom size, apply a width and/or height to the host element.

<sl-animated-image
  src="https://shoelace.style/assets/images/walk.gif"
  alt="Animation of untied shoes walking on pavement"
  style="width: 150px; height: 200px;"
>
</sl-animated-image>

import SlAnimatedImage from '@shoelace-style/shoelace/dist/react/animated-image';

const App = () => (
  <SlAnimatedImage
    src="https://shoelace.style/assets/images/walk.gif"
    alt="Animation of untied shoes walking on pavement"
    style={{ width: '150px', height: '200px' }}
  />
);

Customizing the Control Box

You can change the appearance and location of the control box by targeting the control-box part in your styles. 

<sl-animated-image
  src="https://shoelace.style/assets/images/walk.gif"
  alt="Animation of untied shoes walking on pavement"
  class="animated-image-custom-control-box"
></sl-animated-image>

<style>
  .animated-image-custom-control-box::part(control-box) {
    top: auto;
    right: auto;
    bottom: 1rem;
    left: 1rem;
    background-color: deeppink;
    border: none;
    color: pink;
  }
</style>

import SlAnimatedImage from '@shoelace-style/shoelace/dist/react/animated-image';

const css = `
  .animated-image-custom-control-box::part(control-box) {
    top: auto;
    right: auto;
    bottom: 1rem;
    left: 1rem;
    background-color: deeppink;
    border: none;
    color: pink;
  }
`;

const App = () => (
  <>
    <SlAnimatedImage
      className="animated-image-custom-control-box"
      src="https://shoelace.style/assets/images/walk.gif"
      alt="Animation of untied shoes walking on pavement"
    />

    <style>{css}</style>
  </>
);

Importing

If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

Script Import Bundler React

To import this component from the CDN using a script tag: 

<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.16.0/cdn/components/animated-image/animated-image.js"></script>

To import this component from the CDN using a JavaScript import: 

import 'https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.16.0/cdn/components/animated-image/animated-image.js';

To import this component using a bundler:

import '@shoelace-style/shoelace/dist/components/animated-image/animated-image.js';

To import this component as a React component:

import SlAnimatedImage from '@shoelace-style/shoelace/dist/react/animated-image';

Slots

Name Description
play-icon Optional play icon to use instead of the default. Works best with <sl-icon>.
pause-icon Optional pause icon to use instead of the default. Works best with <sl-icon>.

Learn more about using slots.

Properties

Name Description Reflects Type Default
src The path to the image to load. string -
alt A description of the image used by assistive devices. string -
play Plays the animation. When this attribute is remove, the animation will pause. boolean -
updateComplete A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Events

Name React Event Description Event Detail
sl-load onSlLoad Emitted when the image loads successfully. -
sl-error onSlError Emitted when the image fails to load. -

Learn more about events.

Custom Properties

Name Description Default
--control-box-size The size of the icon box.
--icon-size The size of the play/pause icons.

Learn more about customizing CSS custom properties.

Parts

Name Description
control-box The container that surrounds the pause/play icons and provides their background.

Learn more about customizing CSS parts.

Dependencies

This component automatically imports the following dependencies.

  • <sl-icon>