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 enhancementThis 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 "before" and "after" states of the transition. The structure of the pseudo-elements is dictated by the page-transition-tag property. Specifically, each element that is "tagged" with a page-transition-tag creates a separate snapshot and thus a separate group of pseudo-elements that are animated independently from the rest. Note that for convenience, the root element is tagged with name "root" in the user-agent style sheet.
The groups induced by the page-transition-tag are all positioned within a common pseudo-element root, which itself is attached to the root element of the page.
Each of the groups is comprised of up to four pseudo elements:
Container pseudo-element: this element initially mirrors the size and position of the "before" state element that it represents (i.e. the tagged element that caused this group to be created). The element is animated to the "after" state and position.
Wrapper pseudo-element: this element is a child of the container 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.
Outgoing image: this element is a child of the wrapper element. It is a replaced element that produced the visual representation of the "before" 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.
Incoming image: this element is a child of the wrapper element. It is a replaced element that produces the visual representation of the "after" state, taken from the page’s visual output of the represented elements. Like outgoing 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 how an 'element()' function would work.
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 `signal` on `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 updateDOM 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.
The page-transition-tag property "tags" an element as participating in a page transition.
The element will not participate in a page transition.
The element can participate in a page transition, as either an outgoing or incoming element, with a page transition tag equal to the <custom-ident>'s value.
The value none is invalid as a <custom-ident>.
The root element participates in a page transition by default using the following style in the user-agent origin.
html {
page-transition-tag: root;
}
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 "before" and "after" states. Note that for the purposes of this API, if one element has a tag "foo" in the before state, and another element has a tag "foo" in the after 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. Pseudo-elementsWhile the UA is animating a page transition, it creates the following page-transition pseudo-elements, to represent the various items being animated.
The ::page-transition pseudo-element acts as a grouping element for other page-transition pseudo-elements and has the document’s root element as its originating element.
For example, :root::page-transition selector matches this pseudo-element, but div::page-transition does not.
Other page-transition pseudo-elements take a <pt-tag-selector> argument to specify which elements tagged with page-transition-tag are affected.
There can be multiple pseudo-elements of the same type, one for each page-transition-tag participating in a transition.
The <pt-tag-selector> is defined as follows:
<pt-tag-selector> = '*' | <custom-ident>
A value of * makes the corresponding selector apply to all pseudo elements of the specified type. The specificity of a page-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 page-transition-tag property on an element with the same <custom-ident> value. The specificity of a page-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 page-transition pseudo-elements and their function:
This pseudo-element is the grouping container of all the other page-transition pseudo-elements. Its originating element is the document’s root element.
The following user-agent origin styles apply to this element:
html::page-transition {
position: fixed;
inset: 0;
}
Note: This pseudo-element provides a containing block for all ::page-transition-container pseudo-elements. The aim of the style is to size the pseudo-element to cover the large viewport size and position all ::page-transition-container pseudo-elements relative to the origin of the large viewport.
One of these pseudo-elements exists for each page-transition-tag in a page transition, and holds the rest of the pseudo-elements corresponding to this page-transition-tag.
Its originating element is the ::page-transition pseudo-element.
The following user-agent origin styles apply to this element:
html::page-transition-container(*) {
position: absolute;
top: 0;
left: 0;
animation-duration: 0.25s;
animation-fill-mode: both;
}
Note: The aim of the style is to position the element relative to its ::page-transition parent.
In addition to above, styles in the user-agent origin animate this pseudo-element’s width and height from the size of the outgoing element’s border box to that of the incoming element’s border box. Also the element’s transform is animated from the outgoing element’s screen space transform to the incoming 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.
One of these pseudo-elements exists for each page-transition-tag being in a page transition, and holds the images of the outgoing and incoming elements.
Its originating element is the ::page-transition-container() pseudo-element with the same tag.
The following user-agent origin styles apply to this element:
html::page-transition-image-wrapper(*) {
position: absolute;
inset: 0;
animation-duration: inherit;
animation-fill-mode: inherit;
}
In addition to above, styles in the user-agent origin add ''isolation: isolate'' to this pseudo-element if it has both ::page-transition-incoming-image and ::page-transition-outgoing-image as descendants.
Note: The aim of the style is to position the element to occupy the same space as its ::page-transition-container element and provide isolation for blending.
Isolation is only necessary to get the right cross-fade between incoming and outgoing image pixels. Would it be simpler to always add it and try to optimize in the implementation?
One of these pseudo-elements exists for each element in the outgoing DOM being animated by the page transition, and is a replaced element displaying the outgoing element’s snapshot image. It has natural dimensions equal to the snapshot’s size.
Its originating element is the ::page-transition-image-wrapper() pseudo-element with the same tag.
The following user-agent origin styles apply to this element:
html::page-transition-outgoing-image(*) {
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.
In addition to above, styles in the user-agent origin add mix-blend-mode:plus-lighter to this pseudo element if the ancestor ::page-transition-image-wrapper has both ::page-transition-incoming-image and ::page-transition-outgoing-image as descendants.
Note: mix-blend-mode value of plus-lighter ensures that the blending of identical pixels from the outgoing and incoming images results in the same color value as those pixels.
Additional user-agent origin styles added to animate these pseudo-elements are detailed in Animate a page transition.
Identical to ::page-transition-outgoing-image(), except it deals with the incoming element instead.
The precise tree structure, and in particular the order of sibling pseudo-elements, is defined in the Create transition pseudo-elements algorithm.
5. Concepts 5.1. PhasesPhases 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.
5.2. The page-transition layer stacking layerThis specification introduces a stacking layer to the Elaborate description of Stacking Contexts.
The ::page-transition pseudo-element generates a new stacking context called page-transition layer with the following characteristics:
Its parent stacking context is the root stacking context.
If the page-transition pseudo-element exists, a new stacking context is created for the root and top layer elements. The page-transition layer is a sibling of this stacking context.
The page-transition layer paints after the stacking context for the root and top layer elements.
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 page-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.
Do we need to clarify that the stacking context for the root and top layer elements has filters and effects coming from the root element’s style?
5.3. Captured elementsA captured element is a struct with the following:
an image or null. Initially null.
a set of styles or null. Initially null.
The type of "a set of styles" needs to be linked or defined.
an element or null. Initially null.
Document
A Document additionally has:
a ViewTransition or null. Initially null.
a boolean. Initially false.
Document
partial interface Document {
ViewTransition createTransition(ViewTransitionInit init);
};
dictionary ViewTransitionInit {
required UpdateDOMCallback updateDOM;
};
callback UpdateDOMCallback = Promise<any> ();
6.1.1. createTransition()
If the default animations for the page transition are acceptable, then kicking off a transition requires nothing more than setting
page-transition-tagin the page’s CSS, and a single line of script to start it:
document.createTransition({
updateDOM() {
coolFramework.changeTheDOMToPageB();
}
});
If more precise management is needed, however, transition elements can be managed in script:
async function doTransition() {
// Specify "outgoing" elements. The tag is used to match against
// "incoming" elements they should transition to, and to refer to
// the transitioning pseudo-element.
document.querySelector('.old-message').style.pageTransitionTag = 'message';
const transition = document.createTransition({
async updateDOM() {
// This callback is invoked by the browser when "outgoing"
// 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();
// Tagging elements during the updateDOM() callback marks them as
// "incoming", to be matched up with the same-tagged "outgoing"
// elements marked previously and transitioned between.
document.querySelector('.new-message').style.pageTransitionTag =
'message';
},
});
// 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: '::page-transition-container(message)',
});
// When the finished promise resolves, that means the transition is
// finished.
await transition.finished;
}
6.2. The ViewTransition interface
[Exposed=Window] interfaceViewTransition{ undefined skipTransition(); readonly attribute Promise<undefined>finished; readonly attribute Promise<undefined>ready; readonly attribute Promise<undefined>domUpdated; };
The
ViewTransition
represents and controls a single same-document transition. That is, it controls a transition where the starting and ending document are the same, possibly with changes to the document’s DOM structure.
A ViewTransition has the following:
a map, whose keys are page transition tags and whose values are captured elements. Initially a new map.
One of the following phases:
"`pending-capture`".
"`dom-update-callback-called`".
"`animating`".
"`done`".
an UpdateDOMCallback or null. Initially null.
a Promise. Initially a new promise in this’s relevant Realm.
a Promise. Initially a new promise in this’s relevant Realm.
a Promise. Initially a new promise in this’s relevant Realm.
The finished getter steps are to return this’s finished promise.
The ready getter steps are to return this’s ready promise.
The domUpdated getter steps are to return this’s DOM updated promise.
skipTransition() 7. Algorithms 7.1. Monkey patches to rendering
Issue: Define where this sits within the
update the renderingsteps.
For each Document in docs with a transition suppressing rendering of true:
Define this behavior. Lifecycle updates can still be triggered via script APIs which query style or layout information but no visual updates are presented to the user. Is this the same behavior as render-blocking?
How should input be handled when in this state? The last frame presented to the user will not reflect the DOM state as it asynchronously switches to the new version.
Note: The aim is to prevent unintended DOM updates from being presented to the user after a cached snapshot for the elements has been captured. We wait for one rendering opportunity after prepare to present DOM mutations made by the author before prepare to be presented to the user. This is also the content captured in snapshots.
Note: These steps will be added to the update the rendering in the HTML spec. As such, the prose style is written to match other steps in that algorithm.
7.2. Perform pending transition operations 7.3. Perform an outgoing captureTo
perform an outgoing capturegiven a
ViewTransition transition
, perform the following steps:
Let taggedElements be transition’s tagged elements.
Let usedTransitionTags be a new set of strings.
Let document be transition’s relevant global object’s associated document.
For each element of every Element and pseudo-element connected to document, in [paint order](https://drafts.csswg.org/css2/#painting-order):
The link for "paint order" doesn’t seem right. Is there a more canonical definition?
Let transitionTag be the computed value of page-transition-tag for element.
If transitionTag is none, or element is not rendered, then continue.
If any of the following is true:
usedTransitionTags contains transitionTag.
element is not element’s root and element does not have layout containment.
element is not element’s root and element allows fragmentation.
Then skip the page transition for transition with an "InvalidStateError" DOMException in transition’s relevant Realm, and return.
Append transitionTag to usedTransitionTags.
Let capture be a new captured element struct.
Set capture’s outgoing image to the result of capturing the image of element.
Set capture’s outgoing styles to the following:
A CSS transform that would place element from the layout viewport origin to its current quad.
This value is identity for the root element.
The width and height of element’s border box.
This value is the bounds of the initial containing block for the root element.
An object-view-box value that, when applied to the outgoing image, will cause the view box to coincide with element’s border box in the image.
The writing-mode of element.
The direction of element.
Set taggedElements[transitionTag] to capture.
Set document’s transition suppressing rendering to true.
Queue a global task on the DOM manipulation task source, given transition’s relevant global object, to execute the following steps:
Note: A task is queued here because the texture read back in capturing the image may be async, although the render steps in the HTML spec act as if it’s synchronous.
If transition’s phase is "`done`", then abort these steps.
Note: This happens if transition was skipped before this point.
Call the DOM update callback of transition.
React to transition’s DOM updated promise:
If the promise does not settle within an implementation-defined timeout, then:
If transition’s phase is "`done`", then return.
Note: This happens if transition was skipped before this point.
Skip the page transition transition with a "TimeoutError" DOMException.
If the promise was fulfilled, then:
If transition’s phase is "`done`", then return.
Note: This happens if transition was skipped before this point.
Set transition suppressing rendering to false.
Set usedTransitionTags to a new set.
For each element of every Element and pseudo-element connected to document, in [paint order](https://drafts.csswg.org/css2/#painting-order):
The link for "paint order" doesn’t seem right. Is there a more canonical definition?
Let transitionTag be the computed value of page-transition-tag for element.
If transitionTag is none, or element is not rendered, then continue.
If any of the following is true:
usedTransitionTags contains transitionTag.
element is not element’s root and element does not have layout containment.
element is not element’s root and element allows fragmentation.
Then skip the page transition transition with an "InvalidStateError" DOMException, and return.
Append transitionTag to usedTransitionTags.
If taggedElements[transitionTag] does not exist, then set taggedElements[transitionTag] to a new captured element struct.
Let capture be taggedElements[transitionTag].
Let capture’s incoming element item be element.
Create transition pseudo-elements for transition.
Animate a page transition transition.
Note: This will require running document lifecycle phases to compute information calculated during style/layout.
Note: The frame-by-frame parts of the animation are handled in update transition DOM.
If the promise was rejected with reason r, then:
If transition’s phase is "`done`", then return.
Note: This happens if transition was skipped before this point.
Skip the page transition transition with r.
To
capture the imagegiven an
Element element
, perform the following steps. They return an image.
Render the referenced element and its descendants, at the same size that they would be in the document, over an infinite transparent canvas with the following characteristics:
The origin of element’s ink overflow rectangle is anchored to canvas origin.
If the referenced element has a transform applied to it (or its ancestors), then the transform is ignored.
Note: This transform is applied to the snapshot using the `transform` property of the associated ::page-transition-container pseudo-element.
For each descendant of shadow-including descendant Element and pseudo-element of element, if descendant has a computed value of page-transition-tag that is not none, then skip painting descendant.
Note: This is necessary since the descendant will generate its own snapshot which will be displayed and animated independently.
Refactor this so the algorithm takes a set of elements that will be captured. This centralizes the logic for deciding if an element should be included or not.
Let interestRectangle be the result of computing the interest rectangle for element.
Note: The interestRectangle is the subset of element’s ink overflow rectangle that should be captured. This is required for cases where an element’s ink overflow rectangle needs to be clipped because of hardware constraints. For example, if it exceeds the maximum texture size.
Return the portion of the canvas within interestRectangle as an image. The natural size of the image is equal to the interestRectangle bounds.
To
compute the interest rectangleof an
Element el
, perform the following steps. They return a rectangle.
If el is the document’s root element, then return a rectangle that is the intersection of the layout viewport, including the size of rendered scrollbars (if any), with el’s ink overflow rectangle.
If el’s ink overflow area does not exceed an implementation-defined maximum size, then return a rectangle that is equal to el’s ink overflow rectangle.
Otherwise:
Define the algorithm used to clip the snapshot when it exceeds max size.
To
animate a page transitiongiven a
ViewTransition transition
:
Generate a <keyframe> named "page-transition-fade-out" in user-agent origin as follows:
@keyframes page-transition-fade-out {
to { opacity: 0; }
}
Generate a <keyframe> named "page-transition-fade-in" in user-agent origin as follows:
@keyframes page-transition-fade-in {
from { opacity: 0; }
}
Apply the following styles in user-agent origin:
html::page-transition-outgoing-image(*) {
animation-name: page-transition-fade-out;
}
html::page-transition-incoming-image(*) {
animation-name: page-transition-fade-in;
}
For each tag -> capturedElement of transition’s tagged elements:
If neither of capturedElement’s outgoing image or incoming element is null:
Let transform be capturedElement’s outgoing styles's transform property.
Let width be capturedElement’s outgoing styles's width property.
Let height be capturedElement’s outgoing styles's height property.
Generate a <keyframe> named "page-transition-container-anim-tag" in user-agent origin as follows:
@keyframes page-transition-container-anim-|tag| {
from {
transform: |transform|;
width: |width|;
height: |height|;
}
}
Apply the following styles in user-agent origin:
html::page-transition-container(|tag|) {
animation-name: page-transition-container-anim-|tag|;
}
Set transition’s phase to "`animating`".
To
create transition pseudo-elementsfor a
ViewTransition transition
:
Let transitionRoot be the result of creating a new ::page-transition pseudo-element.
For each transitionTag → capturedElement of transition’s tagged elements:
Let container be the result of creating a new ::page-transition-container pseudo-element with the tag transitionTag.
Append container to transitionRoot.
This should be better defined. I’m not sure if pseudo-elements have defined ways to modify their DOM.
Let width, height, transform, writingMode, and direction be null.
If capturedElement’s incoming element is null, then:
Set width to capturedElement’s outgoing styles width property.
Set height to capturedElement’s outgoing styles height property.
Set transform to capturedElement’s outgoing styles transform property.
Set writingMode to capturedElement’s outgoing styles writing-mode property.
Set direction to capturedElement’s outgoing styles direction property.
Otherwise:
Set width to the current width of capturedElement’s incoming element's border box.
Set height to the current height of capturedElement’s incoming element's border box.
Set transform to a transform that maps the capturedElement’s incoming element's border box from document origin to its quad in layout viewport.
Set writingMode to the computed value of writing-mode on capturedElement’s incoming element.
Set direction to the computed value of direction on capturedElement’s incoming element.
At the user-agent origin, set container’s width, height, transform, writing-mode, and direction properties to width, height, transform, writingMode, and direction.
Let imageWrapper be a new ::page-transition-image-wrapper pseudo-element with the tag transitionTag.
Append imageWrapper to container.
If capturedElement’s outgoing image is not null, then:
Let outgoing be a new ::page-transition-outgoing-image replaced element pseudo-element, with the tag transitionTag, displaying capturedElement’s outgoing image.
Append outgoing to imageWrapper.
At the user-agent origin, set outgoing’s object-view-box property to capturedElement’s outgoing styles object-view-box property.
If capturedElement’s incoming element is not null, then:
Let incoming be a new ::page-transition-incoming-image replaced element pseudo-element, with the tag transitionTag, displaying the capture the image of capturedElement’s incoming element.
Append incoming to imageWrapper.
At the user-agent origin, set incoming’s object-view-box property to a value that when applied to incoming, will cause the view box to coincide with incoming element's border box in the image.
The incoming element and its contents (the flat tree descendants of the element, including both text and elements, or the replaced content of a replaced element), except the page-transition pseudo-elements, are not painted (as if they had visibility: hidden) and do not respond to hit-testing (as if they had pointer-events: none) until incoming exists.
Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.
All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]
Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:
Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:
Note, this is an informative note.
Advisements are normative sections styled to evoke special attention and are set apart from other normative text with <strong class="advisement">, like this: UAs MUST provide an accessible alternative.
A style sheet is conformant to this specification if all of its statements that use syntax defined in this module are valid according to the generic CSS grammar and the individual grammars of each feature defined in this module.
A renderer is conformant to this specification if, in addition to interpreting the style sheet as defined by the appropriate specifications, it supports all the features defined by this specification by parsing them correctly and rendering the document accordingly. However, the inability of a UA to correctly render a document due to limitations of the device does not make the UA non-conformant. (For example, a UA is not required to render color on a monochrome monitor.)
An authoring tool is conformant to this specification if it writes style sheets that are syntactically correct according to the generic CSS grammar and the individual grammars of each feature in this module, and meet all other conformance requirements of style sheets as described in this module.
So that authors can exploit the forward-compatible parsing rules to assign fallback values, CSS renderers must treat as invalid (and ignore as appropriate) any at-rules, properties, property values, keywords, and other syntactic constructs for which they have no usable level of support. In particular, user agents must not selectively ignore unsupported component values and honor supported values in a single multi-value property declaration: if any value is considered invalid (as unsupported values must be), CSS requires that the entire declaration be ignored.
Once a specification reaches the Candidate Recommendation stage, non-experimental implementations are possible, and implementors should release an unprefixed implementation of any CR-level feature they can demonstrate to be correctly implemented according to spec.
To establish and maintain the interoperability of CSS across implementations, the CSS Working Group requests that non-experimental CSS renderers submit an implementation report (and, if necessary, the testcases used for that implementation report) to the W3C before releasing an unprefixed implementation of any CSS features. Testcases submitted to W3C are subject to review and correction by the CSS Working Group.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4