CSS Image Animation

1. Introduction

2. Controlling Image Animations: the image-animation property

This property allows authors to control whether animated images are displayed in their animated state or paused.

Both content images and decorative images are affected by this property. When an element contains several decorative images (e.g. multiple background images or border images), or if it contains both a content image and one or more decorative images, the computed value of the property on that element affects them all.

Note: It is therefore not possible to pause decorative images of an element while letting the animation run on the content image of the same element, nor vice-versa.

In the case of non-animated images, the different values of this property have no effect. This property does not affect videos nor programmatic images either.

normal

The animation of animated images is run normally, as determined by the image format and the host language.

Further, all animated images with the same absolute URL, the same image data, and with an image-animation computed value of normal' must be rendered synchronized to the same timeline as a group, with the timeline starting at the time of the least recent addition to the group.

Note: The above requirement is based on a [HTML] rendering expectation defined in HTML § 15.4.2 Images. As [HTML] does not generally require user agents to present documents in any particular way, and therefore does not normatively require the above behavior. This specification does.

paused

Animated images are rendered as if they were static images: the user agent must not run any animation it contains.

running

Like normal, the animation of animated images is run normally, as determined by the image format and the host language,

However, animation timelines are scoped per element: among the content image and decorative images of a single element, any animated images with the same absolute URL, the same image data, and with an image-animation computed value of running must be rendered synchronized to the same timeline as a group, distinct from the timeline of images in other elements, with the timeline starting at the time of the least recent addition to the group.

:root { /* propagates through the document by inheritance */
  image-animation: paused;
}
img {
  image-animation: normal;
}

The image-animation property affects not only raster image formats, but also to vector images, including SVG (see [SVG2]). However, this is only the case for distinct SVG resources loaded as content images or decorative images, and does not include svg elements inlined into HTML documents. (However, if set on the svg element, it does inherit, and does affect any animated content image loaded via the SVG image element.)

3. Telling Animated Images Apart: the :animated-image pseudo-class

The :animated-image pseudo-class represents content image elements where a animated image has been loaded. For the animated-image pseudo-class to match, the image must not only be in a format that is capable of animation, but must also be an actually animated image.

On elements which do not represent content images, the animated-image pseudo-class never matches.

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

function setImageFocusability(event) {
  var img = event.target;
  if (img.matches(":animated-image") {
    img.tabIndex = 0;
  } else {
    img.removeAttribute("tabindex");
  }
}
document.querySelectorAll("img").forEach( (i) => {
  setImageFocusability({target: i });
  i.addEventListener('load', setImageFocusability);
  i.addEventListener('error', setImageFocusability);
});

Whether :animated-image matches is not affected by the current playing state of the image, nor by the value of the image-animation property. However, if some user agent setting has globally disabled image animations, even images that could otherwise be animated are considered static images, and do not match.

4. Terminology

static image

Images where a single frame is intended to be displayed as the final viewing experience.

A JPEG image is a static image.

animated image

Images where multiple frames are intended to be displayed sequentially as part of the final viewing experience, possibly though not necessarily looping.

An animated PNG image, or an animated [GIF] image are animated images.

Support for progressive rendering or multi-pass loading does not make an image qualify as animated.

content image

An element of the host language representing a static image or an animated image, at the exclusion of videos or programmatic images.

The img [HTML] element, including when it is nested in the picture element; the object [HTML] element, in cases where it represents an image; or the image [SVG2] element represent content images.

decorative image

An image inserted into the document rendering by CSS, through such properties as background-image or border-image.

video

An element of the host language representing a moving picture, typically though not necessarily accompanied by sound, typically though not necessarily presented with interactive controls (for playing, pausing, seeking, controlling the volume, presenting in full screen…), possibly though not necessarily accompanied by captions or subtitles.

Note: From a conceptual point of view, and only based on file formats, videos and animated images have considerable overlap, and cannot not necessarily be distinguished from one another in principle. The distinction here is based on author intent, as expressed through the choice of element in the document.

The video [HTML] element represents a video.

Assuming a user agent which would support both usages, the same video/mp4 file would be considered a video if presented via the video element, or a decorative image if used as a CSS background-image.

programmatic image

An image created programmatically via an API of the host language, as opposed to one loaded from an external resource.

The canvas [HTML] element represents a programmatic image.

Should the video element when it represents its poster frame be treated as a content image, a decorative image, or as (a state of) a video and not an image at all?

5. Accessibility Considerations

6. Privacy Considerations

7. Security Considerations