` element's poster image?
When an element contains several decorative images (e.g. background images *and* border images),
or if it contains both a content image *and* decorative images,
the property affects them all.
In the case of non-animated images,
all values have the same effect (i.e. none).
* **normal**:
The current behavior,
as specified in HTML,
with images auto-playing,
in a loop,
synchronized with other instances of the same image on the page
* **paused**:
the image animation does not run.
* **running**:
the image animation plays,
without synchronization with any other instance of the same image on the page.
### Sample Code Snippets
Turn off all image animations on the page:
```css
:root { image-animation: paused; }
```
Using some knowledge about how the site is structured,
it is possible to fine tune the response to a preference for reduced motion,
for instance suppressing non-essential decorative animations,
while keeping those that are informative components some UI element.
and offering on-demand playback for relevant parts of the content.
```css
@media (prefers-reduced-motion) {
:root { image-animation: paused; }
.loading-indicator { immage-animmation: normal; }
}
```
Elaborate controls to start or stop a paused image can be built with custom markup and script,
but simple cases can be done declaratively.
For instance, you could start paused and play on hover and focus:
```css
img {
image-animation: paused;
filter: grayscale(10%) contrast(50%) brightness(80%);
}
img:hover, img:focus {
filter: none;
image-animation: running;
}
```
Interesting effects can easily be achieved in combination with other CSS:
```css
.carousel {
overflow: scroll;
scroll-snap-type: both mandatory;
}
.carousel img {
scroll-snap-align: center;
image-animation: paused;
}
.carousel img:snapped { image-animation: play; }
```
### Beyond the Basics
A key limitation of the above property is encountered
when authors want to set up a means for users
to selectively activate paused animations:
the author has no means to identify
which images in the page are animated images,
and therefore which images need to be provided
with some a user interface of some kind
to activate the animation.
Two approaches are being considered to complement the basic design above.
#### High-level Approach
An additional value can be added to the `image-animation` property:
* **controlled**:
* on decorative images: same as **paused**
* on content images:
initially, the image animation does not run and the first frame is displayed.
Additionally,
if the underlying image actually is an animatable one,
the user agent provides some UI to allow the user to play and pause the animation,
and also makes the element focusable,
so that the control may be interacted with.
The specific control is UA defined,
but must not change the dimensions of the image.
Authors should not expect more capabilities from this control than the ability to play and pause the animation.
If more is desired, consider using the `` element instead.
With this, some common use-cases are easily handled.
Turning off autoplay on all images, showing UI controls for playback on animatable content images:
```css
:root { image-animation: controlled; }
```
Note that this can be applied just as easily by a site's author, a [web extension](https://w3c.github.io/webextensions/specification/), a user-stylesheet, without any modification to—or knowledge of—the site's markup patterns. Other uses could include a web-based email-client using this to keep animated images under control in HTML email.
Same as above, in response to a [user request for reduced motion](https://drafts.csswg.org/mediaqueries-5/#prefers-reduced-motion):
```css
@media (prefers-reduced-motion) {
:root { image-animation: controlled; }
}
```
#### Low-level Approach
The `:animated-image` pseudo-class can be introduced,
and represents content image elements
where a animated image has been loaded.
While authors can apply `image-animation: paused` to all animated and static images alike
without undesirable side effects,
UI controls to restart the animation should not be added to static images.
This pseudo-class enables targeting only relevant images.
Further, in order to facilitate building UI controls
without having to modify the DOM to add additional markup,
an `::overlay` pseudo-element could be added to `] ? ]`
This example shows how,
when the user prefers reduced motion,
memes in a image gallery could be paused by default,
with a browser-provided play button,
and run once only when activated,
instead of their default state,
which is to autoplay and (generally) to loop forever.
```css
@media (prefers-reduced-motion) {
.funny-meme { image-animation: once controlled; }
}
```
Here, in a hypothetical music playing application,
artwork representing each album plays as a continuous animation
when the element is focused or hovered.
```css
.album-cover { image-animation: paused; }
@media not (prefers-reduced-motion) {
.album-cover:hover,
.album-cover:focus {
image-animation: running loop;
}
}
```
#### Longhands And Further Controls
The property above could be broken down into longhands
possibly similar to those of the `animation-*` family of properties
(`image-animation-play-state`, `image-animation-iteration-count`).
Depending on use cases,
additional properties inspired by `animation-*` properties could also be considered.
Note: if we want to go this way,
it might be better to rename some values discussed above;
names in this explainer were chosen to maximize self-explanatory power,
but if we want to be maximize similarity to the `animation-*` properties,
different names may be better.
For instance,
`loop` in `animation-iteration-count` is actually called `infinite`,
and `once` would be `1`.
#### Control Over the Paused State
The `paused` value could be extended to give control over which frame of the image is displayed when it is stopped.
`paused [ first | last | last-shown | | | ] ?`
### Accessibility Considerations
* Web pages can already contain animated images,
and appropriate `alt` text is already expected to be provided.
”Cartoon coyote being squashed by a falling anvil“
or “cute dancing hamster”
remains equally appropriate and evocative
whether the animation is running or not.
* Currently, screen readers typically do not chose to announce animated images
differently from non-animated images,
though they could if they wanted to.
Similarly, it is not expected that they would announce paused or playing images any differently,
though they could if they wanted to.
* Conversely, when the `controlled` value is specified
on an element containing an actually animated content image,
the element does become focusable so that its controls can be operated,
and screen readers should announce the element distinctly,
similar to how they do for `` elements.
Note that there is precedent for changing the focusability of elements based on CSS:
in addition to a few of properties which can suppress an elements focusability (e.g. `display`, `visibility`…),
`overflow: auto` / `scroll` makes elements focusable,
only when there is something to scroll.
### Privacy Considerations
With regards to decorative images,
this property enables control over image animation cross origin,
without leaking any information about whether the image is actually animatable or not.
The computed value does not change based on this information.
The `running` value has effects that are visibly different on animatable vs non-animatable images,
but none of these differences are observable by the page itself.
With regards to of content images,
the `controlled` value causes the element to become focusable
so that the play/pause control can be keyboard-operated without needing to change the element's tab-index.
This effect is defined to only take effect if the image is actually animatable,
to avoid needlessly making elements focusable and showing disabled/unnecessary controls.
In the case of cross-origin images,
this change of focusability does enable the host page to know
whether the image is animatable or not,
which is otherwise not known from the `` element exposes duration even for cross-origin videos.
A static image is arguably a special case of an animated one with a duration of 0,
so exposing that information is analogous.
* There is a proposal to allow images in the `` element.
If implemented, it means the situation would not just be analogous,
but that whether an image is animatable would already be knowable cross-origin anyway.
## Complementary Solutions
### Images in the `` Element
See [the explainer for “Images in ``”](../images-in-video/README.md).
Animated images are effectively videos without a sound track.
Allowing images in the `` element would take advantage of the rich controls
and APIs afforded to `HTMLMediaElement` in general
and `` in particular,
and is arguably plugging an obvious gap in the web platform.
These approaches are complimentary.
While there is some overlap in terms of what they enable,
they each cover use-cases that the other does not.
Pursuing both would make sense.
***…insert summary table showing overlap and differences…***
### What About ``
have value space that are similar to what is proposed here.
We could consider treating animated images as CSS animations,
and making (all) existing animation properties apply to images with multiple frames,
and attempt to explain the fact that they are animated in terms of CSS properties,
gaining full control over them along the way.
However a “similar“ value space is not an identical value space:
* The some values of `image-animation` are image specific
and are missing from `animation-play-state`,
and would not be generally applicable.
* `animation-iteration-count` lacks a value that can default to what the image specifies internally.
* Various other `animation-*` properties lack values that can express what images need.
For instance, what about `animation-duration`?
* The initial values of the `animation-*` properties are not appropriate for images.
Adding these missing values or smart intial / auto values is certainly possible,
but making the `animation-*` properties be capable of expressing normal image behavior would require significant extensions.
Even if that were done, unless an additional opt-in is added,
this is certain to cause web-compatibility problems,
as `animation-*` properties are widely used on all sorts of elements with decorative or content images,
and so far without any effect.
Turning it on would cause undesired effects in unsuspecting web-sites.
If the regular `animation-*` properties cannot be made to apply by default and would need significant retro-fitting anyway,
it makes little sense to try and shoehorn image animations into them,
even if there are similarities.
### Other Alternatives
***This section is a work in progress.***
Here is a short list,
to be expanded,
of other things that were considered but did not seem like good solutions:
* [Media Fragments](../images-in-video#using-media-fragments)