CSS View Transitions Module Level 1

1. Introduction

This section is non-normative.

View Transitions is a set of API that allow DOM changes to smoothly animate between states. This is accomplished by leveraging user-agents ability to persist visual representations of state (i.e. snapshots) and blend them with current DOM state’s visual output. The API also allows the animations to be customized via standard CSS animation properties.

This spec describes the CSS and JS mechanics of the single-page transition API.

2. Transitions as an enhancement

This section is non-normative.

A key part of this API design is the view that an animated transition is an enhancement to a DOM change. Specifically, there are two components of the API: the DOM change, and the visual state animation.

In order for the user-agent to generate a set of snapshots prior to the DOM change, the API is designed to take the DOM change callback as part of the request to initiate a transition. This means that the user-agent has an opportunity to generate snapshots for the existing visual representation, run the given callback to update the state, and finally generate structures and set up animations required for the transition to occur. All this is accomplished with a single call to the JavaScript API.

The user-agent provides additional JavaScript functionality and promises to control and observe the state of the animations. These are described in detail in the ViewTransition section.

After the callback has finished running, the user-agent creates a structure of pseudo-elements that represent both the "old" and "new" states of the transition. The structure of the pseudo-elements is dictated by the view-transition-name property. Specifically, each element that is named with a view-transition-name creates a separate snapshot and thus a separate group of pseudo-elements that are animated independently from the rest. Note that for convenience, the document element is given the view-transition-name "root" in the user-agent style sheet.

The groups induced by the view-transition-name are all positioned within a common pseudo-element root, which itself is attached to the document element of the page.

Each of the groups is comprised of up to four pseudo elements:

Group

This element initially mirrors the size and position of the "old" element that it represents (i.e. the transition-named element that caused this group to be created). The element is animated to the "new" size and position.

Image-Pair

This element is a child of the group element and provides isolation: isolate for its children. It’s needed so that its children can be blended with non-normal blend modes without affecting other visual outputs.

Old image

This element is a child of the image-pair element. It is a replaced element that produced the visual representation of the "old" state taken from user-agent provided snapshots. Note that the contents of this element can be manipulated with object-* properties in the same way that other replaced elements can be.

New image

This element is a child of the image-pair element. It is a replaced element that produces the visual representation of the "new" state, taken from the page’s visual output of the represented elements. Like the old image, the contents can be manipulated with object-* properties. Note that because this element’s snapshots are taken from the pages output, the visual output changes if the visual output of the represented element changes. This is similar to element(), although it differs in terms of the captured area.

This sections can benefit from diagrams.

Each of the pseudo-elements generated can be targeted by CSS in order to customize its appearance, behavior and/or add animations. This enables full customization of the transition.

Note that because these APIs are an enhancement to the DOM change, some principles emerge:

• If a transition cannot run, or is skipped, the DOM change should still happen. If the DOM change should also be skipped, then that should be handled by another feature. The NavigateEvent is an example of a feature developers could use to handle this.

• Although the transition API allows DOM changes to be asynchronous via the startViewTransition() callback, the transition API is not responsible for queuing or otherwise scheduling the DOM changes, beyond the scheduling needed for the transition itself. Some asynchronous DOM changes can happen concurrently (e.g if they’re happening within independent components), whereas others need to queue, or abort an earlier change. This is best left to a feature or framework that has a more holistic view of the update.

3. CSS properties

3.1. view-transition-name

The view-transition-name property "names" an element as participating in a view transition.

none

The element will not participate in a view transition.

<custom-ident>

The element can participate in a view transition, as either an old or new element, with a view transition name equal to the <custom-ident>'s value.

Note: The value none is invalid as a <custom-ident>.

The document element participates in a view transition by default using the following rule, added to the HTML user agent style sheet:

html {
	view-transition-name: root;
}

Note: This property causes the user-agent to both capture separate snapshots from the elements, as well as create separate pseudo-element sub-trees representing this element’s "old" and "new" states. For the purposes of this API, if one element has a transition-name "foo" in the old state, and another element has a transition-name "foo" in the new state, they are treated as representing different visual state of the same element. This may be confusing, since the elements themselves are not necessarily referring to the same object, but it is a useful model to consider them to be visual states of the same conceptual page entity, that we happen to call "element".

4. User-agent keyframes

The following HTML user agent style sheet:

@keyframes -ua-view-transition-fade-out {
	to { opacity: 0; }
}

@keyframes -ua-view-transition-fade-in {
	from { opacity: 0; }
}

5. Pseudo-elements

The following view-transition pseudo-elements represent the various items being animated.

The ::view-transition pseudo-element acts as a grouping element for other view-transition pseudo-elements and has the document’s originating element.

Note: For example, :root::view-transition selector matches this pseudo-element, but div::view-transition does not.

Other view-transition pseudo-elements take a <pt-name-selector> argument to specify which elements named with view-transition-name are affected.

There can be multiple pseudo-elements of the same type, one for each view-transition-name participating in a transition.

The <pt-name-selector> is defined as follows:

<pt-name-selector> = '*' <custom-ident>

A value of * makes the corresponding selector apply to all pseudo elements of the specified type. The specificity of a view-transition selector with a * argument is zero.

The <custom-ident> value makes the corresponding selector apply to exactly one pseudo element of the specified type, namely the pseudo-element that is created as a result of the view-transition-name property on an element with the same <custom-ident> value. The specificity of a view-transition selector with a <custom-ident> argument is the same as for other pseudo-elements, and is equivalent to a type selector.

The following describes all of the view-transition pseudo-elements and their function:

::view-transition

This pseudo-element is the grouping container of all the other view-transition pseudo-elements. Its document element.

The following is added to the HTML user agent style sheet:

html::view-transition {
	position: fixed;
	inset: 0;
}

Note: This pseudo-element provides a containing block for all ::view-transition-group() pseudo-elements. The aim of the style is to size the pseudo-element to cover the snapshot viewport and position all ::view-transition-group() pseudo-elements relative to the snapshot viewport origin.

::view-transition-group( <pt-name-selector> )

One of these pseudo-elements exists for each view-transition-name in a view transition, and holds the rest of the pseudo-elements corresponding to this view-transition-name.

Its originating element is the ::view-transition pseudo-element.

The following is added to the HTML user agent style sheet:

html::view-transition-group(*) {
	position: absolute;
	top: 0;
	left: 0;

	animation-duration: 0.25s;
	animation-fill-mode: both;
}

The aim of the style is to position the element relative to its ::view-transition parent.

In addition to above, styles in the view transition style sheet animate this pseudo-element’s border box to that of the new element’s border box. Also the element’s transform is animated from the old element’s screen space transform to the new element’s screen space transform. This style is generated dynamically since the values of animated properties are determined at the time that the transition begins.

The selector for this and subsequently defined pseudo-elements is likely to change to indicate position in the pseudo-tree hierarchy.

::view-transition-image-pair( <pt-name-selector> )

One of these pseudo-elements exists for each view-transition-name being in a view transition, and holds the images of the old and new elements.

Its originating element is the ::view-transition-group() pseudo-element with the same transition-name.

The following is added to the HTML user agent style sheet:

html::view-transition-image-pair(*) {
	position: absolute;
	inset: 0;

	animation-duration: inherit;
	animation-fill-mode: inherit;
}

Note: The aim of the style is to position the element to occupy the same space as its ::view-transition-group() element.

::view-transition-old( <pt-name-selector> )

One of these pseudo-elements exists for each element in the old DOM being animated by the view transition, and is a replaced element displaying the old element’s snapshot image. It has natural dimensions equal to the snapshot’s size.

Its originating element is the ::view-transition-image-pair() pseudo-element with the same transition-name.

The following is added to the HTML user agent style sheet:

html::view-transition-old(*) {
	position: absolute;
	inset-block-start: 0;
	inline-size: 100%;
	block-size: auto;

	animation-duration: inherit;
	animation-fill-mode: inherit;
}

Note: The aim of the style is to match the element’s inline size while retaining the aspect ratio. It is also placed at the block start.

Note: Additional styles in the view transition style sheet added to animate these pseudo-elements are detailed in setup transition pseudo-elements and update pseudo-element styles.

::view-transition-new( <pt-name-selector> )

Identical to ::view-transition-old(), except it deals with the new element instead.

The precise tree structure, and in particular the order of sibling pseudo-elements, is defined in the setup transition pseudo-elements algorithm.

6. Concepts

6.1. Phases

Phases represent an ordered sequence of states. Since phases are ordered, prose can refer to phases before a particular phase, meaning they appear earlier in the sequence, or after a particular phase, meaning they appear later in the sequence.

The initial phase is the first item in the sequence.

Note: For the most part, a developer using this API does not need to worry about the different phases, since they progress automatically. It is, however, important to understand what steps happen in each of the phases: when the snapshots are captured, when pseudo-element DOM is created, etc. The description of the phases below tries to be as precise as possible, with an intent to provide an unambiguous set of steps for implementors to follow in order to produce a spec-compliant implementation.

6.2. The snapshot viewport

The snapshot viewport covers all areas of the window that could potentially display web content. This area is consistent regardless of root scrollbars or interactive widgets.

"Interactive widgets" refers to UI described within a property definition in CSS Viewport § 3.4 interactive-widget. This should be extracted into an exported definition that can be used independently of the property.

This means the snapshot canvas size is likely to be consistent for the document element's old image and new element.

The snapshot viewport origin refers to the start of the block and inline axes of the snapshot viewport.

6.3. The view-transition layer stacking layer

This specification introduces a stacking layer to the CSS 2 §  Elaborate description of Stacking Contexts.

The ::view-transition pseudo-element generates a new stacking context called the view-transition layer with the following characteristics:

• Its parent stacking context is the root stacking context.

• If the ::view-transition pseudo-element exists, a new stacking context is created for the top layer. The view-transition layer is a sibling of this stacking context.

• The view-transition layer paints after the stacking context for the top layer.

• The view-transition layer is positioned at the snapshot viewport origin, and is the same size as the snapshot viewport. As in, it covers the snapshot viewport.

Note: The intent of the feature is to be able to capture the contents of the page, which includes the top layer elements. In order to accomplish that, the view-transition layer cannot be a part of the captured top layer context, since that results in a circular dependency. Instead, this stacking context is a sibling of other page contents.

Create a diagram to explain these stacking contexts.

Do we need to clarify that the stacking context for the root and top layer elements has filters and effects coming from the document element's style?

6.4. Captured elements

A captured element is a struct with the following:

old image

an image or null. Initially null.

The type of "image" needs to be linked or defined.

old styles

a set of styles or null. Initially null.

The type of "a set of styles" needs to be linked or defined.

new element

an element or null. Initially null.

The type of "element" needs to be linked or defined.

In addition, a captured element has the following style definitions:

group keyframes

A CSSKeyframesRule or null. Initially null.

group animation name rule

A CSSStyleRule or null. Initially null.

group styles rule

A CSSStyleRule or null. Initially null.

old view-box rule

A CSSStyleRule or null. Initially null.

new view-box rule

A CSSStyleRule or null. Initially null.

image pair isolation rule

A CSSStyleRule or null. Initially null.

view blend mode rule

A CSSStyleRule or null. Initially null.

Note: These are used to update, and later remove styles from a document's view transition style sheet.

6.5. Additions to Document

A Document additionally has:

active DOM transition

a ViewTransition or null. Initially null.

transition suppressing rendering

a boolean. Initially false.

view transition style sheet

a style sheet. Initially a new style sheet in the HTML user agent style sheet.

Note: This is used to hold dynamic styles relating to transitions.

7. API

7.1. Additions to Document

partial interface Document {
  ViewTransition startViewTransition(optional UpdateDOMCallback? callback = null);
};

callback UpdateDOMCallback = any> ();

7.1.1. startViewTransition()

document.startViewTransition(async () => {
	await coolFramework.changeTheDOMToPageB();
});

async function doTransition() {
	/ Specify "old" elements. The name is used to match against
	/ "new" elements they should transition to, and to refer to
	/ the transitioning pseudo-element.
	document.querySelector(".old-message").style.viewTransitionName = "message";

	const transition = document.startViewTransition(async () => {
		/ This callback is invoked by the browser when "old"
		/ capture finishes and the DOM can be switched to the new
		/ state. No frames are rendered until this callback returns.

		/ DOM changes may be asynchronous
		await coolFramework.changeTheDOMToPageB();

		/ Naming elements during the callback marks them as
		/ "new", to be matched up with the same-named "old"
		/ elements marked previously and transitioned between.
		document.querySelector(".new-message").style.viewTransitionName = "message";

		/ viewTransitionNames must be unique, so the above assumes that
		/ <code data-opaque bs-autolink-syntax='`.old-message`'>.old-message</code> has been removed/hidden by <code data-opaque bs-autolink-syntax='`changeTheDOMToPageB()`'>changeTheDOMToPageB()</code>.
	});

	/ When ready resolves, all pseudo-elements for this transition have
	/ been generated.
	/ They can now be accessed in script to set up custom animations.
	await transition.ready;

	document.documentElement.animate(keyframes, {
		...animationOptions,
		pseudoElement: "::view-transition-group(message)",
	});

	/ When the finished promise resolves, that means the transition is
	/ finished.
	await transition.finished;
}

[Exposed=Window]
interface ViewTransition {
  undefined skipTransition();
  readonly attribute undefined> finished;
  readonly attribute undefined> ready;
  readonly attribute undefined> domUpdated;
};

8.2. Perform pending transition operations

8.3. Setup view transition