Animated Image
<cs-animated-image>
Animated images display GIFs and WEBPs with controls to play and pause them on demand. Use them when you want motion but need to give users control over when it plays.
This component uses <canvas> to draw freeze frames, so images are subject to cross-origin restrictions.
Examples
Image Formats
Both GIF and WEBP images are supported.
Width & Height
To set a custom size, apply a width and/or height to the host element.
Customizing the Control Box
You can change the appearance and location of the control box by targeting the control-box part in your styles.
API
Importing
If you're using the autoloader or a hosted project, components load on demand — no manual import needed. To cherry-pick this component, use one of the following snippets.
import '@cruglobal/cornerstone-components/components/animated-image/animated-image.js';
import './cornerstone/components/animated-image/animated-image.js';
import CsAnimatedImage from '@cruglobal/cornerstone-components/react/animated-image/index.js';
Slots
Learn more about using slots.
| Name | Description |
|---|---|
pause-icon | Optional pause icon to use instead of the default. Works best with <cs-icon>. |
play-icon | Optional play icon to use instead of the default. Works best with <cs-icon>. |
Attributes & Properties
Learn more about attributes and properties.
| Property | Attribute | Description | Type | Default | Reflects |
|---|---|---|---|---|---|
alt | alt | A description of the image used by assistive devices. | string | — | — |
play | play | Plays the animation. When this attribute is remove, the animation will pause. | boolean | — | Yes |
src | src | The path to the image to load. | string | — | — |
Events
Learn more about events.
| Name | Description |
|---|---|
cs-error | Emitted when the image fails to load. |
cs-load | Emitted when the image loads successfully. |
CSS Custom Properties
Learn more about CSS custom properties.
| Name | Description | Default |
|---|---|---|
--control-box-size | The size of the icon box. | — |
--icon-size | The size of the play/pause icons. | — |
CSS Parts
Learn more about CSS parts.
| Name | Description | CSS selector |
|---|---|---|
control-box | The container that surrounds the pause/play icons and provides their background. | ::part(control-box) |
Dependencies
This component automatically imports the following elements. Sub-dependencies, if any exist, are included in this list.
SSR
Learn more about Server-Side Rendering (SSR).
Due to browser limitations, <cs-animated-image> can't render during SSR. As a fallback you can use a <video> tag, but its controls won't work, and the gif or webp will always auto-play.