CSS Image Animation

Authors: Florian Rivoal, Lea Verou

Previous Version: https://github.com/webplatformco/project-image-animation/blob/main/image-animation-property/README.md

  1. User Needs & Use Cases
  2. User Research
    1. Developer & User signals
    2. Current Workarounds
  3. Goals
    1. Non-goals
  4. Proposed Solution
    1. Sample Code Snippets
    2. Beyond the Basics
      1. High-level Solution
      2. Low-level Solution
    3. Possible Extensions
      1. Control Over Iterations
      2. Longhands And Further Controls
      3. Control Over the Paused State
    4. Accessibility Considerations
    5. Privacy Considerations
  5. Complementary Solutions
    1. Images in the <video> Element
    2. What About <img control>?
  6. Rejected Alternatives
    1. Provide this as a UA Setting
    2. Reuse the Existing animation-* Properties
    3. Other Alternatives

User Needs & Use Cases

Animated images (as enabled by GIF, APNG, WebP) are in common use on the web, for a variety of reasons, such as:

By default, UAs autoplay these images, which can be jarring for users, especially in use cases where there are multiple images on a single page (e.g. image galleries) and violates WCAG, and currently, site authors have no control over this.

This leads to a user desire to control such animations. However, due to the diversity of usage, there is a wide range of use cases and desired UIs and user experiences, so making this an automatic or opt-in UA feature would not be sufficient.

To offer their users the best experience, websites need to control the playback experience, separately for each different uses of animated images. For example:

In some cases, this can already be done using alternatives to animated images, such as CSS animations, SVG, or <video> elements, which give authors different ways to control playback. But this is not always practical:

User Research

Developer & User Signals

A few examples amongst many of people asking for that type of functionality.

Current Workarounds

Numerous workarounds exist (further highlighting author/user demand), all with a variety of downsides. See the “Current Workarounds” section of the Images-in-video explainer for a brief discussion.

Goals

Non-goals

Proposed Solution

The proposed solution is a css property to control animation of images. At its most basic version, it would take the following form:

Name: image-animation Value: normal | paused | running Initial: normal Applies to: see text Inherited: yes Computed Value: specified keyword

This property applies to:

This property has no effect on other types of graphical content, such as <video> elements, or <canvas>.

Issue: what about <object>, <embed>, <svg>, or the <video> 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).

Sample Code Snippets

Turn off all image animations on the page:

: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.

@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:

img {
  image-animation: paused;
  filter: grayscale(10%) contrast(50%) brightness(80%);
}
img:hover, img:focus {
  filter: none;
  image-animation: running;
}

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:

With this, some common use-cases are easily handled.

Turning off autoplay on all images, showing UI controls for playback on animatable content images:

:root { image-animation: controlled; }

Note that this can be applied just as easily by a site's author, a web extension, 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:

@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 <img> enabling generated content or other effects to be easily placed over the image.

Possible Extensions

Control Over Iterations

Animated image formats such as GIF, WebP, or APNG include information about how many times the animation is supposed to run. This could be made into an overridable default, with alternate possibilities being specified in CSS.

normal | paused | [ [ running | controlled ] && [ once | loop ] ? ]

or more generally:

normal | paused | [ [ running | controlled ] && [ loop | <integer [1,∞]>] ? ]

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.

@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.

.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 | <time> | <percent> | <number> ] ?

Accessibility Considerations

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 <img> element. Similarly, the :animated-image pseudo-class also reveals whether an image is animated or not, including cross origin. Either of these effects could be blocked by invoking CORS, however, this proposal chooses not to. We argue that this is an acceptable trade-off:

Complementary Solutions

Images in the <video> Element

See the explainer for “Images in <video>”.

Animated images are effectively videos without a sound track. Allowing images in the <video> element would take advantage of the rich controls and APIs afforded to HTMLMediaElement in general and <video> 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 <img control>?

…insert discussion of why that's not a full substitute, but of how both features can be made compatible with each other if that's desired…

Rejected Alternatives

Provide this as a UA Setting

Firefox's about:config has image.animation_mode, which can turn off all image animations, and Safari respects macOS's “auto-play animated images” setting (default on, can be turn off). However, such settings are too blunt an instrument to handle all cases. The browser doesn't know which images are decorative ones whose animation can be suppressed outright when users want reduced motion, and which are content, which should remain viewable if desired (but maybe upon clicking some play button or on hover). As it is, if the browser forcibly suppresses animation of images, users will either no have means to individually turn them back on (as is case for Safari and Firefox). Alternatively, if they have some UI element for every paused image, even the decorative ones with superfluous animations would get such a button, and possibly worse if animated images are used as part of some UI component, UI injected by indiscriminately by the browser might clash with the site's own UI. Say, for example, that a flashy/tacky website has pulsating / sparkling images used as buttons. It wouldn't be great if a GIF-stopping browser added play buttons onto that site's GIF-based buttons, it's GIF-based checkboxes, etc. But if it doesn't, it also doesn't add them to animated images which are meaningful parts of the content, since it doesn't reliably know which is which.

In a browser where image-animation is implemented, this UI setting could continue to exist, possibly implemented in different ways. The most blunt way is to simply make all images non animated when the setting is on, leaving the CSS property nothing to usefully take effect on. More interestingly, the setting could be reinterpreted in terms of the CSS property,

@media (prefers-reduced-motion) {
  *,
  *::before,
  *::after,
  *::marker {
    image-animation: controlled !important;
  }
}

Reuse the Existing animation-* Properties

Properties like animation-play-state: running | paused or animation-iteration-count: infinite | <number [0,∞]> 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:

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: