Title: CSS Image Animation Module Level 1
Shortname: css-image-animation
Level: 1
group: csswg
Status: ED
Prepare for TR: no
Work Status: exploring
ED: https://drafts.csswg.org/css-image-animation-1/
TR: https://www.w3.org/TR/css-image-animation-1/
Previous Version: https://webplatform.design/projects/image-animation/image-animation-property/spec/overview
Editor: Florian Rivoal, http://florian.rivoal.net, w3cid 43241
Complain About: accidental-2119 yes, missing-example-ids yes
Infer CSS Dfns: yes
Markup Shorthands: markdown yes, css yes
Abstract: This CSS module proposes facilities to control the rendering of animated images.

	spec:html; type:element; text:body

{
	"IMAGE-ANIMATION-EXPLAINER": {
		"authors": [
		  "Florian Rivoal",
		  "Lea Verou"
		],
		"href": "https://drafts.csswg.org/css-image-animation-1/explainer",
		"title": "CSS Image Animation Explainer"
	  },
	"IMAGE-ANIMATION-TALK": {
		"authors": [
		  "Lea Verou",
		  "Florian Rivoal"
		],
		"href": "https://github.com/webplatformco/project-image-animation/tree/main/image-animation-property",
		"title": "We need to be able to control Image Animation on the Web Platform!"
	  }
}

	Name: image-animation
	Value: normal | paused | stopped | running
	Initial: normal
	Applies to: [=content images=] and elements with [=decorative images=]
	Inherited: yes
	Computed Value: as specified
	Animation Type: discrete
	

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/rendering#images-3]]. 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.

stopped

[=Animated images=] are rendered as if they were [=static images=]: the user agent must not run any animation it contains. If the image contains a [=cover frame=], that is what the user agent must use; otherwise, it must display the image as it would be in the initial state of the animation.

paused

The user agent must not run the animation contained in the [=Animated images=], and must continue to display the image as it was when this value started to apply, effectively pausing the animation. If the animation had not been playing prior to this value being applied, the behavior is the same as ''stopped''.

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. If images are added to the element while the computed value is ''running'', the timeline starts at the time of the least recent addition to the group. If the element is created or made visible after having previously been set to ''display: none'', with images already added and with 'image-animation' already set to ''running'', the timeline starts when the element is included in the layout. If this property is switched to ''running'' from another value, the beginnig of this timeline is set so that the animation continues from the state that was displayed at the timem of the switch.

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

		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);
			});
			

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 image|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=]. When it represents its poster frame (and only then), the HTML <{video}> element is considered a [=content image=].

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=].

cover frame

Some [=animated image=] formats make it possible for the creator of the image to specify a [=static image=], referred to in this document as the [=cover frame=], to display when the animation is not running, distinctly from the initial state of the animation.

• none