Animated Image
Examples
WEBP Images
Setting a Width and Height
Customizing the Control Box
Importing
Slots
Properties
Events
Custom Properties
Parts
Dependencies

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"
  />
);

This component uses <canvas> to draw freeze frames, so images are subject to cross-origin restrictions.

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.19.1/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.19.1/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	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>