Animated Image

sl-animated-image

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

Examples

Basic Animated Image

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

sl-animated-image 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.

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>

sl-animated-image 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>

sl-animated-image 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>

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

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

Component Props

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

Learn more about attributes and properties.

Slots

Name	Details
`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.

Events

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

Learn more about events.

Custom Properties

Name	Details
`--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.

CSS 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>