CSS View Transitions Module Level 1

CSS View Transitions Module Level 1
CSS View Transitions Module Level 1
Editor’s Draft
16 February 2025
More details about this document
This version:
Latest published version:
Implementation Report:
Feedback:
CSSWG Issues Repository
Editors:
Tab Atkins-Bittner
Google
Jake Archibald
Google
Khushal Sagar
Google
Suggest an Edit for this Spec:
GitHub Editor
World Wide Web Consortium
W3C
liability
trademark
and
permissive document license
rules apply.
Abstract
This module defines the View Transition API, along with associated properties and pseudo-elements,
which allows developers to create animated visual transitions representing changes in the document state.
CSS
is a language for describing the rendering of structured documents
(such as HTML and XML)
on screen, on paper, etc.
Status of this document
This is a public copy of the editors’ draft.
It is provided for discussion only and may change at any moment.
Its publication here does not imply endorsement of its contents by W3C.
Don’t cite this document other than as work in progress.
Please send feedback
by
filing issues in GitHub
(preferred),
including the spec code “css-view-transitions” in the title, like this:
“[css-view-transitions]
…summary of comment…
”.
All issues and comments are
archived
Alternately, feedback can be sent to the (
archived
) public mailing list
www-style@w3.org
This document is governed by the
18 August 2025 W3C Process Document
1.
Introduction
This section is non-normative.
This specification introduces a DOM API and associated CSS features
that allow developers to create animated visual transitions,
called
view transitions
between different states of a
document
1.1.
Separating Visual Transitions from DOM Updates
Traditionally, creating a visual transition between two document states
required a period where both states were present in the DOM at the same time.
In fact, it usually involved creating a specific DOM structure
that could represent both states.
For example, if one element was “moving” between containers,
that element often needed to exist outside of either container for the period of the transition,
to avoid clipping from either container or their ancestor elements.
This extra in-between state often resulted in UX and accessibility issues,
as the structure of the DOM was compromised for a purely-visual effect.
View Transitions
avoid this troublesome in-between state
by allowing the DOM to switch between states instantaneously,
then performing a customizable visual transition between the two states in another layer,
using a static visual capture of the old state, and a live capture of the new state.
These captures are represented as a tree of
pseudo-elements
(detailed in
§ 3.2 View Transition Pseudo-elements
),
where the old visual state co-exists with the new state,
allowing effects such as cross-fading
while animating from the old to new size and position.
1.2.
View Transition Customization
By default,
document.
startViewTransition()
creates a
view transition
consisting of
a page-wide cross-fade between the two DOM states.
Developers can also choose which elements are captured independently
using the
view-transition-name
CSS property,
allowing these to be animated independently of the rest of the page.
Since the transitional state (where both old and new visual captures exist)
is represented as
pseudo-elements
developers can customize each transition using familiar features
such as
CSS Animations
and
Web Animations
1.3.
View Transition Lifecycle
A successful
view transition
goes through the following phases:
Developer calls
document.
startViewTransition
updateCallback
which returns a
ViewTransition
viewTransition
Current state captured as the “old” state.
Rendering paused.
Developer’s
updateCallback
function, if provided, is called,
which updates the document state.
viewTransition
updateCallbackDone
fulfills.
Current state captured as the “new” state.
Transition pseudo-elements created.
See
§ 3.2 View Transition Pseudo-elements
for an overview of this structure.
Rendering unpaused, revealing the transition pseudo-elements.
viewTransition
ready
fulfills.
Pseudo-elements animate until finished.
Transition pseudo-elements removed.
viewTransition
finished
fulfills.
1.4.
Transitions as an enhancement
A key part of the View Transition API design
is that an animated transition is a visual
enhancement
to an underlying document state change.
That means a failure to create a visual transition,
which can happen due to misconfiguration or device constraints,
will not prevent the developer’s
ViewTransitionUpdateCallback
being called,
even if it’s known in advance that the transition animations cannot happen.
For example, if the developer calls
skipTransition()
at the start of the
view transition lifecycle
the steps relating to the animated transition,
such as creating the
view transition tree
will not happen.
However, the
ViewTransitionUpdateCallback
will still be called.
It’s only the visual transition that’s skipped,
not the underlying state change.
Note:
If the DOM change should also be skipped,
then that needs to be handled by another feature.
navigateEvent
signal
is an example of a feature developers could use to handle this.
Although the View Transition API allows DOM changes to be asynchronous via the
ViewTransitionUpdateCallback
the API is not responsible for queuing or otherwise scheduling DOM changes
beyond any 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 application.
1.5.
Rendering Model
View Transition works by replicating an element’s rendered state using UA generated
pseudo-elements
Aspects of the element’s rendering which apply to the element itself or its descendants,
for example visual effects like
filter
or
opacity
and clipping from
overflow
or
clip-path
are applied when generating its image in
Capture the image
However, properties like
mix-blend-mode
which define how the element draws when it is embedded can’t be applied to its image.
Such properties are applied to the element’s corresponding
::view-transition-group()
pseudo-element,
which is meant to generate a box equivalent to the element.
If the
::view-transition-group()
has a corresponding element in the "new" states,
the browser keeps the properties copied over to the
::view-transition-group()
in sync with the DOM element in the "new" state.
If the
::view-transition-group()
has corresponding elements both in the "old" and "new" state,
and the property being copied is interpolatable,
the browser also sets up a default animation to animate the property smoothly.
1.6.
Examples
Taking a page that already updates its content using a pattern like this:
function
spaNavigate
data
updateTheDOMSomehow
data
);
view transition
could be added like this:
function
spaNavigate
data
// Fallback for browsers that don't support this API:
if
document
startViewTransition
updateTheDOMSomehow
data
);
return
// With a transition:
document
startViewTransition
(()
=>
updateTheDOMSomehow
data
));
This results in the default transition of a quick cross-fade:
The cross-fade is achieved using CSS animations on a
tree of pseudo-elements
so customizations can be made using CSS. For example:
::view-transition-old
root
),
::view-transition-new
root
animation-duration
This results in a slower transition:
Building on the previous example, motion can be added:
@keyframes
fade-in
from
opacity
@keyframes
fade-out
to
opacity
@keyframes
slide-from-right
from
transform
translateX
30
px
);
@keyframes
slide-to-left
to
transform
translateX
-30
px
);
::view-transition-old
root
animation
90
ms
cubic-bezier
0.4
both fade-out
300
ms
cubic-bezier
0.4
0.2
both slide-to-left
::view-transition-new
root
animation
210
ms
cubic-bezier
0.2
90
ms
both fade-in
300
ms
cubic-bezier
0.4
0.2
both slide-from-right
Here’s the result:
Building on the previous example,
the header and text within the header can be given their own
::view-transition-group()
s for the transition:
.main-header
view-transition-name
main-header
.main-header-text
view-transition-name
main-header-text
/* Give the element a consistent size, assuming identical text: */
width: fit-content
By default, these groups will transition size and position from their “old” to “new” state,
while their visual states cross-fade:
Building on the previous example, let’s say some pages have a sidebar:
In this case, things would look better if the sidebar was static if it was in both the “old” and “new” states.
Otherwise, it should animate in or out.
The
:only-child
pseudo-class can be used to create animations specifically for these states:
.sidebar
view-transition-name
sidebar
@keyframes
slide-to-right
to
transform
translateX
30
px
);
/* Entry transition */
::view-transition-new
sidebar
:only-child
animation
300
ms
cubic-bezier
0.2
both fade-in
300
ms
cubic-bezier
0.4
0.2
both slide-from-right
/* Exit transition */
::view-transition-old
sidebar
:only-child
animation
150
ms
cubic-bezier
0.4
both fade-out
300
ms
cubic-bezier
0.4
0.2
both slide-to-right
For cases where the sidebar has both an “old” and “new” state, the default animation is correct.
Not building from previous examples this time,
let’s say we wanted to create a circular reveal from the user’s cursor.
This can’t be done with CSS alone.
Firstly, in the CSS, allow the “old” and “new” states to layer on top of one another without the default blending,
and prevent the default cross-fade animation:
::view-transition-image-pair
root
isolation
auto
::view-transition-old
root
),
::view-transition-new
root
animation
none
mix-blend-mode
normal
Then, the JavaScript:
// Store the last click event
let
lastClick
addEventListener
'click'
event
=>
lastClick
event
));
function
spaNavigate
data
// Fallback for browsers that don't support this API:
if
document
startViewTransition
updateTheDOMSomehow
data
);
return
// Get the click position, or fallback to the middle of the screen
const
lastClick
clientX
??
innerWidth
const
lastClick
clientY
??
innerHeight
// Get the distance to the furthest corner
const
endRadius
Math
hypot
Math
max
innerWidth
),
Math
max
innerHeight
);
// Create a transition:
const
transition
document
startViewTransition
(()
=>
updateTheDOMSomehow
data
);
});
// Wait for the pseudo-elements to be created:
transition
ready
then
(()
=>
// Animate the root's new view
document
documentElement
animate
clipPath
`circle(0 at
${
px
${
px)\`,
\`circle(
${
endRadius
px at
${
px
${
px)\`,
],
},
duration: 500,
easing: 'ease-in',
// Specify which pseudo-element to animate
pseudoElement: '::view-transition-new(root)',
);
});
And here’s the result:
2.
CSS properties
2.1.
Tagging Individually Transitioning Subtrees: the
view-transition-name
property
Name:
view-transition-name
Value:
none

Initial:
none
Applies to:
all elements
Inherited:
no
Percentages:
n/a
Computed value:
as specified
Canonical order:
per grammar
Animation type:
discrete
Note:
though
view-transition-name
is
discretely animatable
, animating it doesn’t
affect the running view transition. Rather, it’s a way to set its value in a way that can change
over time or based on a
timeline
. An example for using this would be to change the
view-transition-name
based on
scroll-driven animations
The
view-transition-name
property “tags” an element
for
capture in a view transition
tracking it independently in the
view transition tree
under the specified
view transition name
An element so captured is animated independently of the rest of the page.
none
The
element
will not participate independently in a view transition.

The
element
participates independently in a view transition—​as either an old or new
element
—​with the specified
view transition name
Each
view transition name
is a
tree-scoped name
Note:
Since currently only document-scoped view transitions are supported, only view transition names that are associated with the document are respected.
The values
none
auto
, and
match-element
are excluded from

here.
Note:
If this name is not unique
(i.e. if two elements simultaneously specify the same
view transition name
then the
view transition
will abort.
Note:
For the purposes of this API,
if one element has
view transition name
foo
in the old state,
and another element has
view transition name
foo
in the new state,
they are treated as representing different visual state of the same element,
and will be paired in the
view transition tree
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.
If the element’s
principal box
is
fragmented
skipped
or
not rendered
this property has no effect.
See
§ 7 Algorithms
for exact details.
To get the
document-scoped view transition name
for an
Element
element
Let
scopedViewTransitionName
be the
computed value
of
view-transition-name
for
element
If
scopedViewTransitionName
is associated with
element
’s
node document
, then return
scopedViewTransitionName
Otherwise, return
none
2.1.1.
Rendering Consolidation
Elements
captured in a view transition
during a
view transition
or whose
view-transition-name
computed value
is not
none
(at any time):
Form a
stacking context
Are
flattened in 3D transforms
Form a
backdrop root
3.
Pseudo-elements
3.1.
Pseudo-element Trees
Note:
This is a general definition for trees of pseudo-elements. If other features need this behavior, these definitions will be moved to
[css-pseudo-4]
pseudo-element root
is a type of
tree-abiding pseudo-element
that is the
root
in a
tree
of
tree-abiding pseudo-elements
known as the
pseudo-element tree
The
pseudo-element tree
defines the document order of its
descendant
tree-abiding pseudo-elements
When a
pseudo-element
participates
in a
pseudo-element tree
its
originating pseudo-element
is its
parent
If a
descendant
pseudo
of a
pseudo-element root
has no other
siblings
then
:only-child
matches that
pseudo
Note:
This means that
::view-transition-new(ident):only-child
will only select
::view-transition-new(ident)
if the parent
::view-transition-image-pair(ident)
contains a single
child
As in, there is no
sibling
::view-transition-old(ident)
3.2.
View Transition Pseudo-elements
The visualization of a
view transition
is represented as a
pseudo-element tree
called the
view transition tree
composed of the
view transition pseudo-elements
defined below.
This tree is built during the
setup transition pseudo-elements
step,
and is rooted under a
::view-transition
pseudo-element
originating
from the
root element
All of the
view transition pseudo-elements
are selected
from their
ultimate originating element
, the
document element
The
view transition tree
is not exposed to the accessibility tree.
For example,
the
::view-transition-group()
pseudo-element is attached to the root element selector directly,
as in
:root::view-transition-group()
it is not attached to its parent, the
::view-transition
pseudo-element.
Once the user-agent has captured both the “old” and “new” states of the document,
it creates a structure of pseudo-elements like the following:
::view-transition
├─ ::view-transition-group(name)
│ └─ ::view-transition-image-pair(name)
│ ├─ ::view-transition-old(name)
│ └─ ::view-transition-new(name)
└─ …other groups…
Each element with a
view-transition-name
is captured separately,
and a
::view-transition-group()
is created for each unique
view-transition-name
For convenience, the
document element
is given the
view-transition-name
"root" in the
user-agent style sheet
Either
::view-transition-old()
or
::view-transition-new()
are absent in cases where the capture does not have an “old” or “new” state.
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.
3.2.1.
Named View Transition Pseudo-elements
Several of the
view transition pseudo-elements
are
named view transition pseudo-elements
which are
functional
tree-abiding
view transition pseudo-elements
associated with a
view transition name
These
pseudo-elements
take a

as their argument,
and their syntax follows the pattern:
::view-transition-
pseudo

where

selects a
view transition name
and has the following syntax definition:

= '*'

named view transition pseudo-element
selector
only matches
a corresponding
pseudo-element
if its

matches that
pseudo-element
’s
view transition name
i.e. if it is either
or a matching

Note:
The
view transition name
of a
view transition pseudo-element
is set to the
view-transition-name
that triggered its creation.
The specificity of a
named view transition pseudo-element
selector
with a

argument
is equivalent to a
type selector
The specificity of a
named view transition pseudo-element
selector
with a
argument
is zero.
3.2.2.
View Transition Tree Root: the
::view-transition
pseudo-element
The
::view-transition
pseudo-element
is a
tree-abiding pseudo-element
that is also a
pseudo-element root
Its
originating element
is the document’s
document element
and its
containing block
is the
snapshot containing block
Note:
This element serves as the
parent
of all
::view-transition-group()
pseudo-elements.
3.2.3.
View Transition Named Subtree Root: the
::view-transition-group()
pseudo-element
The
::view-transition-group()
pseudo-element
is a
named view transition pseudo-element
that represents a matching named
view transition
capture.
::view-transition-group()
pseudo-element
is generated for each
view transition name
as a
child
of the
::view-transition
pseudo-element
and contains a corresponding
::view-transition-image-pair()
This element initially mirrors the size and position of the “old” element,
or the “new” element if there isn’t an “old” element.
If there’s both an “old” and “new” state,
styles in the
dynamic view transition style sheet
animate this pseudo-element’s
width
and
height
from the size of the old 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.
3.2.4.
View Transition Image Pair Isolation: the
::view-transition-image-pair()
pseudo-element
The
::view-transition-image-pair()
pseudo-element
is a
named view transition pseudo-element
that represents a pair of corresponding old/new
view transition
captures.
This pseudo-element is a
child
of the corresponding
::view-transition-group()
pseudo-element
and contains
a corresponding
::view-transition-old()
pseudo-element
and/or
a corresponding
::view-transition-new()
pseudo-element
(in that order).
This element exists to provide
isolation: isolate
for its children,
and is always present as a
child
of each
::view-transition-group()
This isolation allows the image pair to be blended with non-normal blend modes
without affecting other visual outputs. As such, the developer would typically not
need to add custom styles to the
::view-transition-image-pair()
pseudo-element.
Instead, a typical design would involve styling the
::view-transition-group()
::view-transition-old()
, and
::view-transition-new()
pseudo-elements.
3.2.5.
View Transition Old State Image: the
::view-transition-old()
pseudo-element
The
::view-transition-old()
pseudo-element
is an empty
named view transition pseudo-element
that represents a visual snapshot of the “old” state as a
replaced element
it is omitted if there’s no “old” state to represent.
Each
::view-transition-old()
pseudo-element is a
child
of the corresponding
::view-transition-image-pair()
pseudo-element.
:only-child
can be used to match cases where this element is the only element in the
::view-transition-image-pair()
The appearance of this element can be manipulated with
object-*
properties in the same way that other replaced elements can be.
Note:
The content and
natural dimensions
of the image are captured in
capture the image
and set in
setup transition pseudo-elements
Note:
Additional styles in the
dynamic view transition style sheet
added to animate these pseudo-elements
are detailed in
setup transition pseudo-elements
and
update pseudo-element styles
3.2.6.
View Transition New State Image: the
::view-transition-new()
pseudo-element
The
::view-transition-new()
pseudo-element
(like the analogous
::view-transition-old()
pseudo-element)
is an empty
named view transition pseudo-element
that represents a visual snapshot of the “new” state as a
replaced element
it is omitted if there’s no “new” state to represent.
Each
::view-transition-new()
pseudo-element is a
child
of the corresponding
::view-transition-image-pair()
pseudo-element.
Note:
The content and
natural dimensions
of the image are captured in
capture the image
then set and updated in
setup transition pseudo-elements
and
update pseudo-element styles
4.
View Transition Layout
The
view transition pseudo-elements
are styled, laid out, and rendered like normal elements,
except that they originate in the
snapshot containing block
rather than the
initial containing block
and are painted in the
view transition layer
above the rest of the document.
4.1.
The Snapshot Containing Block
The
snapshot containing block
is a rectangle
that covers all areas of the window that could potentially display page content
(and is therefore consistent regardless of root scrollbars or
interactive widgets
).
This makes it likely to be consistent for the
document element
’s
old image
and
new element
Within a
child navigable
, the
snapshot containing block
is the union of the navigable’s
viewport
with any
scrollbar gutters
An example of the
snapshot containing block
on a mobile OS.
The snapshot includes the URL bar, as this can be scrolled away.
The keyboard is included as this appears and disappears.
The top and bottom bars are part of the OS rather than the browser, so they’re not included in the snapshot containing block.
An example of the
snapshot containing block
on a desktop OS.
This includes the scrollbars, but does not include the URL bar, as web content never appears in that area.
The
snapshot containing block origin
refers to the top-left corner of the
snapshot containing block
The
snapshot containing block size
refers to the width and height of the
snapshot containing block
as a
tuple
of two numbers.
The
snapshot containing block
is considered to be an
absolute positioning containing block
and a
fixed positioning containing block
for
::view-transition
and its descendants.
4.2.
View Transition Painting Order
This specification introduces a new stacking layer, the
view transition layer
to the end of the painting order established in
CSS2§E Elaborate Description of Stacking Contexts
[CSS2]
The
::view-transition
pseudo-element
generates a new stacking context,
called the
view transition layer
which paints after all other content of the document
(including any content rendered in the
top layer
),
after any filters and effects that are applied to such content.
(It is not subject to such filters or effects,
except insofar as they affect the rendered contents
of the
::view-transition-old()
and
::view-transition-new()
pseudo-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
view transition layer
cannot be a part of the captured stacking contexts,
since that results in a circular dependency.
Therefore, the
view transition layer
is a sibling of all other content.
When a
Document
’s
active view transition
’s
phase
is "
animating
",
the boxes generated by any element in that
Document
with
captured in a view transition
and its
element contents
except
transition root pseudo-element
’s
inclusive descendants
are not painted (as if they had
opacity: 0
) and
do not respond to hit-testing (as if they had
pointer-events: none
).
Note:
Elements participating in a transition need to skip painting in their DOM location because
their image is painted in the corresponding
::view-transition-new()
pseudo-element instead.
Similarly, hit-testing is skipped because the element’s DOM location does not correspond to where its contents are rendered.
However, there is no change in how these elements are accessed by assistive technologies or the accessibility tree.
5.
User Agent Stylesheet
The
global view transition user agent style sheet
is
user-agent origin
style sheet containing the following rules:
:root
view-transition-name
root
:root::view-transition
position
absolute
inset
:root::view-transition-group
position
absolute
top
left
animation-duration
0.25
animation-fill-mode
both
:root::view-transition-image-pair
position
absolute
inset
:root::view-transition-old
),
:root::view-transition-new
position
absolute
inset-block-start
inline-size
100
block-size
auto
:root::view-transition-image-pair
),
:root::view-transition-old
),
:root::view-transition-new
animation-duration
inherit
animation-fill-mode
inherit
animation-delay
inherit
animation-timing-function
inherit
animation-iteration-count
inherit
animation-direction
inherit
animation-play-state
inherit
/* Default cross-fade transition */
@keyframes
-ua-view-transition-fade-out
to
opacity
@keyframes
-ua-view-transition-fade-in
from
opacity
/* Keyframes for blending when there are 2 images */
@keyframes
-ua-mix-blend-mode-plus-lighter
from
mix-blend-mode
plus-lighter
to
mix-blend-mode
plus-lighter
Explanatory Summary
This UA style sheet does several things:
Lay out
::view-transition
to cover the entire
snapshot containing block
so that each
:view-transition-group()
child can lay out relative to it.
Give the
root element
a default
view transition name
to allow it to be independently selected.
Reduce layout interference from the
::view-transition-image-pair()
pseudo-element
so that authors can essentially treat
::view-transition-old()
and
::view-transition-new()
as direct children of
::view-transition-group()
for most purposes.
Inherit animation timing through the tree so that by default,
the animation timing set on a
::view-transition-group()
will dictate the animation timing of all its descendants.
Style the element captures
::view-transition-old()
and
::view-transition-new()
to match the size and position set on
::view-transition-group()
(insofar as possible without breaking their aspect ratios)
as it interpolates between them.
Since the sizing of these elements depends on the mapping between logical and physical coordinates,
dynamic view transition style sheet
copies relevant styles from the DOM elements.
Set up a default quarter-second cross-fade animation
for each
::view-transition-group()
Additional styles are dynamically added to the
user-agent origin
during a
view transition
through the
dynamic view transition style sheet
6.
API
6.1.
Additions to
Document
partial
interface
Document
ViewTransition
startViewTransition
optional
ViewTransitionUpdateCallback
updateCallback
);
};
callback
ViewTransitionUpdateCallback
Promise
any
> ();
viewTransition
document
startViewTransition
updateCallback
Starts a new
view transition
(canceling the
document
’s existing
active view transition
, if any).
updateCallback
, if provided, is called asynchronously, once the current state of the document is captured.
Then, when the promise returned by
updateCallback
fulfills,
the new state of the document is captured
and the transition is initiated.
Note that
updateCallback
, if provided, is
always
called,
even if the transition cannot happen
(e.g. due to duplicate
view-transition-name
values).
The transition is an enhancement around the state change, so a failure to create a transition never prevents the state change.
See
§ 1.4 Transitions as an enhancement
for more details on this principle.
If the promise returned by
updateCallback
rejects, the transition is skipped.
6.1.1.
startViewTransition()
Method Steps
The
method steps
for
startViewTransition(
updateCallback
are as follows:
Let
transition
be a new
ViewTransition
object in
this’s
relevant Realm
If
updateCallback
is provided, set
transition
’s
update callback
to
updateCallback
Let
document
be
this’s
relevant global object’s
associated document
If
document
’s
visibility state
is "
hidden
",
then
skip
transition
with an "
InvalidStateError
DOMException
and return
transition
If
document
’s
active view transition
is not null,
then
skip that view transition
with an "
AbortError
DOMException
in
this’s
relevant Realm
Note:
This can result in two asynchronous
update callbacks
running concurrently
(and therefore possibly out of sequence):
one for the
document
’s current
active view transition
, and another for this
transition
As per the
design of this feature
, it’s assumed that the developer is using another feature or framework to correctly schedule these DOM changes.
Set
document
’s
active view transition
to
transition
Note:
The
view transition
process continues in
setup view transition
via
perform pending transition operations
Return
transition
6.2.
The
ViewTransition
interface
Exposed
Window
interface
ViewTransition
readonly
attribute
Promise
undefined
updateCallbackDone
readonly
attribute
Promise
undefined
ready
readonly
attribute
Promise
undefined
finished
undefined
skipTransition
();
};
The
ViewTransition
interface represents and controls a single same-document
view transition
i.e. a transition where the starting and ending document are the same,
possibly with changes to the document’s DOM structure.
viewTransition
updateCallbackDone
A promise that fulfills when the promise returned by
updateCallback
fulfills, or rejects when it rejects.
Note:
The View Transition API wraps a DOM change and creates a visual transition.
However, sometimes you don’t care about the success/failure of the transition animation,
you just want to know if and when the DOM change happens.
updateCallbackDone
is for that use-case.)
viewTransition
ready
A promise that fulfills once the
pseudo-elements
for the transition are created,
and the animation is about to start.
It rejects if the transition cannot begin.
This can be due to misconfiguration, such as duplicate
view-transition-name
s,
or if
updateCallbackDone
returns a rejected promise.
The point that
ready
fulfills
is the ideal opportunity to animate the
view transition pseudo-elements
with the
Web Animation API
viewTransition
finished
A promise that fulfills once the end state is fully visible and interactive to the user.
It only rejects if
updateCallback
returns a rejected promise,
as this indicates the end state wasn’t created.
Otherwise, if a transition fails to begin,
or is skipped (by
skipTransition()
),
the end state is still reached,
so
finished
fulfills.
viewTransition
skipTransition
()
Immediately finish the transition, or prevent it starting.
This never prevents
updateCallback
being called,
as the DOM change is independent of the transition.
See
§ 1.4 Transitions as an enhancement
for more details on this principle.
If this is called before
ready
resolves,
ready
will reject.
If
finished
hasn’t resolved, it will fulfill or reject along with
updateCallbackDone
ViewTransition
has the following:
named elements
map
, whose keys are
view transition names
and whose values are
captured elements
Initially a new
map
Note: Since this is associated to the
ViewTransition
, it will be cleaned up when
Clear view transition
is called.
phase
One of the following ordered phases, initially "
pending-capture
":
pending-capture
".
update-callback-called
".
animating
".
done
".
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.
update callback
ViewTransitionUpdateCallback
or null. Initially null.
ready promise
Promise
Initially
a new promise
in
this’s
relevant Realm
update callback done promise
Promise
Initially
a new promise
in
this’s
relevant Realm
Note:
The
ready promise
and
update callback done promise
are immediately created,
so rejections will cause
unhandledrejection
s unless they’re
handled
even if the getters such as
updateCallbackDone
are not accessed.
finished promise
Promise
Initially
a new promise
in
this’s
relevant Realm
marked as handled
Note:
This is
marked as handled
to prevent duplicate
unhandledrejection
s,
as this promise only ever rejects along with the
update callback done promise
transition root pseudo-element
::view-transition
Initially a new
::view-transition
initial snapshot containing block size
tuple
of two numbers (width and height), or null.
Initially null.
Note:
This is used to detect changes in the
snapshot containing block size
which causes the transition to
skip
Discussion of this behavior
The
finished
getter steps
are to return
this’s
finished promise
The
ready
getter steps
are to return
this’s
ready promise
The
updateCallbackDone
getter steps
are to return
this’s
update callback done promise
6.2.1.
skipTransition()
Method Steps
The
method steps
for
skipTransition()
are:
If
this
’s
phase
is not "
done
",
then
skip the view transition
for
this
with an "
AbortError
DOMException
7.
Algorithms
7.1.
Data Structures
7.1.1.
Additions to
Document
Document
additionally has:
active view transition
ViewTransition
or null. Initially null.
rendering suppression for view transitions
a boolean. Initially false.
While a
Document
’s
rendering suppression for view transitions
is true,
all pointer hit testing must target its
document element
ignoring all other
elements
Note:
This does not affect pointers that are
captured
dynamic view transition style sheet
style sheet
Initially a new
style sheet
in the
user-agent origin
, ordered after the
global view transition user agent style sheet
Note:
This is used to hold dynamic styles relating to transitions.
show view transition tree
A boolean. Initially false.
When this is true,
this
’s
active view transition
’s
transition root pseudo-element
renders as a child of
this
’s
document element
with
this
’s
document element
being its
originating element
Note:
The position of the
transition root pseudo-element
within the
document element
does not matter, as the
transition root pseudo-element
’s
containing block
is the
snapshot containing block
update callback queue
list
, initially empty.
7.1.2.
Additions to Elements
Elements
have a
captured in a view transition
boolean, initially false.
Note:
This spec uses CSS’s definition of
element
, which includes
pseudo-elements
7.1.3.
Captured elements
captured element
is a
struct
with the following:
old image
an 2D bitmap or null. Initially null.
old width
old height
an
unrestricted double
, initially zero.
old transform

, initially the
identity transform function
old writing-mode
Null or a
writing-mode
, initially null.
old direction
Null or a
direction
, initially null.
old text-orientation
Null or a
text-orientation
, initially null.
old mix-blend-mode
Null or a
mix-blend-mode
, initially null.
old backdrop-filter
Null or a
backdrop-filter
, initially null.
old color-scheme
Null or a
color-scheme
, initially null.
new element
an
element
or null. Initially null.
In addition, a
captured element
has the following
style definitions
group keyframes
CSSKeyframesRule
or null. Initially null.
group animation name rule
CSSStyleRule
or null. Initially null.
group styles rule
CSSStyleRule
or null. Initially null.
image pair isolation rule
CSSStyleRule
or null. Initially null.
image animation name rule
CSSStyleRule
or null. Initially null.
Note:
These are used to update, and later remove styles
from a
document
’s
dynamic view transition style sheet
7.2.
Perform pending transition operations
This algorithm is invoked as a part of
update the rendering loop
in the html spec.
To
perform pending transition operations
given a
Document
document
, perform the following steps:
If
document
’s
active view transition
is not null, then:
If
document
’s
active view transition
’s
phase
is "
pending-capture
",
then
setup view transition
for
document
’s
active view transition
Otherwise, if
document
’s
active view transition
’s
phase
is "
animating
",
then
handle transition frame
for
document
’s
active view transition
7.3.
Setup view transition
To
setup view transition
for a
ViewTransition
transition
perform the following steps:
Note:
This algorithm captures the current state of the document,
calls the transition’s
ViewTransitionUpdateCallback
then captures the new state of the document.
Let
document
be
transition
’s
relevant global object’s
associated document
Flush the update callback queue
Note:
this ensures that any changes to the DOM scheduled by other skipped transitions are done before the old state for this transition is captured.
Capture the old state
for
transition
If failure is returned, then
skip the view transition
for
transition
with an "
InvalidStateError
DOMException
in
transition
’s
relevant Realm
and return.
Set
document
’s
rendering suppression for view transitions
to true.
Queue a global task
on the
DOM manipulation task source
given
transition
’s
relevant global object
to perform 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.
schedule the update callback
for
transition
Flush the update callback queue
To
activate view transition
for a
ViewTransition
transition
perform the following steps:
If
transition
’s
phase
is "
done
", then return.
Note:
This happens if
transition
was
skipped
before this point.
Set
transition
’s
relevant global object’s
associated document
’s
rendering suppression for view transitions
to false.
If
transition
’s
initial snapshot containing block size
is not equal to the
snapshot containing block size
then
skip
transition
with an "
InvalidStateError
DOMException
in
transition
’s
relevant Realm
and return.
Capture the new state
for
transition
If failure is returned, then
skip
transition
with an "
InvalidStateError
DOMException
in
transition
’s
relevant Realm
and return.
For each
capturedElement
of
transition
’s
named elements
values
If
capturedElement
’s
new element
is not null,
then set
capturedElement
’s
new element
’s
captured in a view transition
to true.
Setup transition pseudo-elements
for
transition
Update pseudo-element styles
for
transition
If failure is returned, then
skip the view transition
for
transition
with an "
InvalidStateError
DOMException
in
transition
’s
relevant Realm
and return.
Note:
The above steps will require running document lifecycle phases,
to compute information calculated during style/layout.
Set
transition
’s
phase
to "
animating
".
Resolve
transition
’s
ready promise
7.3.1.
Capture the old state
To
capture the old state
for
ViewTransition
transition
Let
document
be
transition
’s
relevant global object’s
associated document
Let
namedElements
be
transition
’s
named elements
Let
usedTransitionNames
be a new
set
of strings.
Let
captureElements
be a new
list
of elements.
If the
snapshot containing block size
exceeds an
implementation-defined
maximum, then return failure.
Set
transition
’s
initial snapshot containing block size
to the
snapshot containing block size
For each
element
of every
element
that is
connected
and has a
node document
equal to
document
in
paint order
We iterate in paint order to ensure that this order is cached in
namedElements
This defines the DOM order for
::view-transition-group
pseudo-elements
, such that the element at the bottom of the paint stack generates the first pseudo child of
::view-transition
If any
flat tree
ancestor of this
element
skips its contents
, then
continue
If
element
has more than one
box fragment
, then
continue
Note:
We might want to enable transitions for fragmented elements in future versions.
See
#8900
Note:
box fragment
here does not refer to fragmentation of
inline boxes
across
line boxes
Such inlines can participate in a transition.
Let
transitionName
be the
element
’s
document-scoped view transition name
If
transitionName
is
none
or
element
is
not rendered
then
continue
If
usedTransitionNames
contains
transitionName
, then:
For each
element
in
captureElements
Set
element
’s
captured in a view transition
to false.
return failure.
Append
transitionName
to
usedTransitionNames
Set
element
’s
captured in a view transition
to true.
Append
element
to
captureElements
The algorithm continues in a separate loop to ensure that
captured in a view transition
is set on all elements participating in this capture before it is read by future steps in the algorithm.
For each
element
in
captureElements
Let
capture
be a new
captured element
struct.
Set
capture
’s
old image
to the result of
capturing the image
of
element
Let
originalRect
be
snapshot containing block
if
element
is the
document element
otherwise, the
element
’s
border box
Set
capture
’s
old width
to
originalRect
’s
width
Set
capture
’s
old height
to
originalRect
’s
height
Set
capture
’s
old transform
to a

that would map
element
’s
border box
from the
snapshot containing block origin
to its
current visual position.
Set
capture
’s
old writing-mode
to the
computed value
of
writing-mode
on
element
Set
capture
’s
old direction
to the
computed value
of
direction
on
element
Set
capture
’s
old text-orientation
to the
computed value
of
text-orientation
on
element
Set
capture
’s
old mix-blend-mode
to the
computed value
of
mix-blend-mode
on
element
Set
capture
’s
old backdrop-filter
to the
computed value
of
backdrop-filter
on
element
Set
capture
’s
old color-scheme
to the
computed value
of
color-scheme
on
element
Let
transitionName
be the
computed value
of
view-transition-name
for
element
Set
namedElements
transitionName
] to
capture
For each
element
in
captureElements
Set
element
’s
captured in a view transition
to false.
7.3.2.
Capture the new state
To
capture the new state
for
ViewTransition
transition
Let
document
be
transition
’s
relevant global object’s
associated document
Let
namedElements
be
transition
’s
named elements
Let
usedTransitionNames
be a new
set
of strings.
For each
element
of every
element
that is
connected
and has a
node document
equal to
document
in
paint order
If any
flat tree
ancestor of this
element
skips its contents
, then
continue
Let
transitionName
be
element
’s
document-scoped view transition name
If
transitionName
is
none
or
element
is
not rendered
then
continue
If
element
has more than one
box fragment
, then
continue
If
usedTransitionNames
contains
transitionName
then return failure.
Append
transitionName
to
usedTransitionNames
If
namedElements
transitionName
] does not
exist
then set
namedElements
transitionName
] to a new
captured element
struct.
Note:
We intentionally add this struct to the end of this ordered map.
This implies than names which only exist in the new DOM (entry animations) will be painted on top of names only in the old DOM (exit animations) and names in both DOMs (paired animations).
This might not be the right layering for all cases. See
issue 8941
Set
namedElements
transitionName
]'s
new element
to
element
7.3.3.
Setup transition pseudo-elements
To
setup transition pseudo-elements
for a
ViewTransition
transition
Note:
This algorithm constructs the
pseudo-element tree
for the transition,
and generates initial styles.
The structure of the pseudo-tree is covered at a higher level in
§ 3.2 View Transition Pseudo-elements
Let
document
be
transition
’s
relevant global object’s
associated document
Set
document
’s
show view transition tree
to true.
For each
transitionName
capturedElement
of
transition
’s
named elements
Let
group
be a new
::view-transition-group()
with its
view transition name
set to
transitionName
Append
group
to
transition
’s
transition root pseudo-element
Let
imagePair
be a new
::view-transition-image-pair()
with its
view transition name
set to
transitionName
Append
imagePair
to
group
If
capturedElement
’s
old image
is not null, then:
Let
old
be a new
::view-transition-old()
with its
view transition name
set to
transitionName
displaying
capturedElement
’s
old image
as its
replaced
content.
Append
old
to
imagePair
If
capturedElement
’s
new element
is not null, then:
Let
new
be a new
::view-transition-new()
with its
view transition name
set to
transitionName
Note:
The styling of this pseudo is handled in
update pseudo-element styles
Append
new
to
imagePair
If
capturedElement
’s
old image
is null, then:
Assert
capturedElement
’s
new element
is not null.
Set
capturedElement
’s
image animation name rule
to a new
CSSStyleRule
representing the following CSS,
and append it to
document
’s
dynamic view transition style sheet
:root::view-transition-new
transitionName
animation-name
-ua-view-transition-fade-in
Note:
The above code example contains variables to be replaced.
If
capturedElement
’s
new element
is null, then:
Assert
capturedElement
’s
old image
is not null.
Set
capturedElement
’s
image animation name rule
to a new
CSSStyleRule
representing the following CSS,
and append it to
document
’s
dynamic view transition style sheet
:root::view-transition-old
transitionName
animation-name
-ua-view-transition-fade-out
Note:
The above code example contains variables to be replaced.
If both of
capturedElement
’s
old image
and
new element
are not null, then:
Let
transform
be
capturedElement
’s
old transform
Let
width
be
capturedElement
’s
old width
Let
height
be
capturedElement
’s
old height
Let
backdropFilter
be
capturedElement
’s
old backdrop-filter
Set
capturedElement
’s
group keyframes
to a new
CSSKeyframesRule
representing the following CSS,
and append it to
document
’s
dynamic view transition style sheet
@keyframes
-ua-view-transition-group-anim-
transitionName
from
transform
transform
width
width
height
height
backdrop-filter
backdropFilter
Note:
The above code example contains variables to be replaced.
Set
capturedElement
’s
group animation name rule
to a new
CSSStyleRule
representing the following CSS,
and append it to
document
’s
dynamic view transition style sheet
:root::view-transition-group
transitionName
animation-name
-ua-view-transition-group-anim-
transitionName
Note:
The above code example contains variables to be replaced.
Set
capturedElement
’s
image pair isolation rule
to a new
CSSStyleRule
representing the following CSS,
and append it to
document
’s
dynamic view transition style sheet
:root::view-transition-image-pair
transitionName
isolation
isolate
Note:
The above code example contains variables to be replaced.
Set
capturedElement
’s
image animation name rule
to a new
CSSStyleRule
representing the following CSS,
and append it to
document
’s
dynamic view transition style sheet
:root::view-transition-old
transitionName
animation-name
-ua-view-transition-fade-out
-ua-mix-blend-mode-plus-lighter
:root::view-transition-new
transitionName
animation-name
-ua-view-transition-fade-in
-ua-mix-blend-mode-plus-lighter
Note:
The above code example contains variables to be replaced.
Note:
mix-blend-mode: plus-lighter
ensures
that the blending of identical pixels from the old and new images
results in the same color value as those pixels,
and achieves a “correct” cross-fade.
7.4.
Call the update callback
To
call the update callback
of a
ViewTransition
transition
Note:
This is guaranteed to happen for every
ViewTransition
even if the transition is
skipped
The reasons for this are discussed in
§ 1.4 Transitions as an enhancement
Assert
transition
’s
phase
is "
done
", or before "
update-callback-called
".
If
transition
’s
phase
is not "
done
", then set
transition
’s
phase
to "
update-callback-called
".
Let
callbackPromise
be null.
If
transition
’s
update callback
is null,
then set
callbackPromise
to
a promise resolved with
undefined,
in
transition
’s
relevant Realm
Otherwise, set
callbackPromise
to the result of
invoking
transition
’s
update callback
Let
fulfillSteps
be to following steps:
Resolve
transition
’s
update callback done promise
with undefined.
Activate
transition
Let
rejectSteps
be the following steps given
reason
Reject
transition
’s
update callback done promise
with
reason
If
transition
’s
phase
is "
done
", then return.
Note:
This happens if
transition
was
skipped
before this point.
Mark as handled
transition
’s
ready promise
Note:
transition
’s
update callback done promise
will provide the
unhandledrejection
This step avoids a duplicate.
Skip the view transition
transition
with
reason
React
to
callbackPromise
with
fulfillSteps
and
rejectSteps
To skip a transition after a timeout, the user agent may perform the following steps
in parallel
Wait for an implementation-defined
duration
Queue a global task
on the
DOM manipulation task source
given
transition
’s
relevant global object
, to perform the following steps:
If
transition
’s
phase
is "
done
", then return.
Note:
This happens if
transition
was
skipped
before this point.
Skip
transition
with a "
TimeoutError
DOMException
To
schedule the update callback
given a
ViewTransition
transition
Append
transition
to
transition
’s
relevant settings object
’s
update callback queue
Queue a global task
on the
DOM manipulation task source
given
transition
’s
relevant global object
, to
flush the update callback queue
To
flush the update callback queue
given a
Document
document
For each
transition
in
document
’s
update callback queue
call the update callback
given
transition
Set
document
’s
update callback queue
to an empty list.
7.5.
Skip the view transition
To
skip the view transition
for
ViewTransition
transition
with reason
reason
Let
document
be
transition
’s
relevant global object’s
associated document
Assert
transition
’s
phase
is not "
done
".
If
transition
’s
phase
is before "
update-callback-called
",
then
schedule the update callback
for
transition
Set
rendering suppression for view transitions
to false.
If
document
’s
active view transition
is
transition
Clear view transition
transition
Set
transition
’s
phase
to "
done
".
Reject
transition
’s
ready promise
with
reason
Note:
The
ready promise
may already be resolved at this point,
if
skipTransition()
is called after we start animating.
In that case, this step is a no-op.
Resolve
transition
’s
finished promise
with the result of
reacting
to
transition
’s
update callback done promise
If the promise was fulfilled, then return undefined.
Note:
Since the rejection of
transition
’s
update callback done promise
isn’t explicitly handled here,
if
transition
’s
update callback done promise
rejects,
then
transition
’s
finished promise
will reject with the same reason.
7.6.
View transition page-visibility change steps
The
view transition page-visibility change steps
given
Document
document
are:
Queue a global task
on the
DOM manipulation task source
given
document
’s
relevant global object
to perform the following steps:
If
document
’s
visibility state
is "
hidden
", then:
If
document
’s
active view transition
is not null, then
skip
document
’s
active view transition
with an "
InvalidStateError
DOMException
Otherwise,
assert
active view transition
is null.
Note:
this is called from the HTML spec.
7.7.
Capture the image
To
capture the image
given an
element
element
, perform the following steps.
They return an image.
If
element
is the
document element
, then:
Render the region of document
(including its
canvas background
and any
top layer
content)
that intersects the
snapshot containing block
on a transparent canvas the size of the
snapshot containing block
following the
capture rendering characteristics
, and these additional characteristics:
Areas outside
element
’s
scrolling box
should be rendered as if they were scrolled to, without moving or resizing the
layout viewport
This must not trigger events related to scrolling or resizing, such as
IntersectionObserver
s.
An example of what the user sees compared to the captured snapshot.
This example assumes the root is the only element with a transition name.
Areas that cannot be scrolled to (i.e. they are out of scrolling bounds),
should render the
canvas background
An example of what the user sees compared to the captured snapshot.
This example assumes the root is the only element with a transition name.
Return this canvas as an image.
The natural size of the image is equal to the
snapshot containing block
Otherwise:
Render
element
and its
descendants
at the same size it appears in its
node document
over an infinite transparent canvas,
following the
capture rendering characteristics
Return the portion of this canvas that includes
element
’s
ink overflow rectangle
as an image.
The
natural dimensions
of this image must be those of its
principal
border box
and its origin must correspond to that
border box
’s origin,
such that the image represents the contents of this
border box
and any captured
ink overflow
is represented outside these bounds.
Note:
When this image is rendered as a
replaced element
at its
natural size
it will display with the size and contents of element’s
principal box
with any captured
ink overflow
overflowing its
content box
7.7.1.
Capture rendering characteristics
The
capture rendering characteristics
are as follows:
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
::view-transition-group
pseudo-element
Effects applied on the element and its descendants, such as
opacity
and
filter
, are applied to the capture.
Effects applied to the element from its ancestors are ignored.
Implementations may clip the rendered contents if the
ink overflow rectangle
exceeds some
implementation-defined
maximum.
However, the captured image should include, at the very least, the contents of
element
that intersect with the
snapshot containing block
Implementations may adjust the rasterization quality to account for elements with a large
ink overflow area
that are transformed into view.
Implementations may also adjust the rasterization quality for elements whose
ink overflow rectangle
does not intersect with the
snapshot containing block
To avoid a broken experience if the element ends up becoming visible, the captured image should include, at the very least, some low-quality representation of the contents rather than transparent pixels.
Note:
This allows efficiency in resource usage and rasterization performance for elements that are away from the viewport and might not become visible at all,
while maintaining a visual effect close enough to the author’s intent.
For each
descendant
of
shadow-including descendant
Element
and
pseudo-element
of
element
if
descendant
is
captured in a view transition
then skip painting
descendant
Note:
This is necessary since the descendant will generate its own snapshot which will be displayed and animated independently.
7.8.
Handle transition frame
To
handle transition frame
given a
ViewTransition
transition
Let
document
be
transition
’s
relevant global object’s
associated document
Let
hasActiveAnimations
be a boolean, initially false.
For each
element
of
transition
’s
transition root pseudo-element
’s
inclusive descendants
For each
animation
whose
timeline
is a
document timeline
associated with
document
and contains at least one
associated effect
whose
effect target
is
element
set
hasActiveAnimations
to true if any of the following conditions are true:
animation
’s
play state
is
paused
or
running
document
’s
pending animation event queue
has any events associated with
animation
If
hasActiveAnimations
is false:
Set
transition
’s
phase
to "
done
".
Clear view transition
transition
Resolve
transition
’s
finished promise
Return.
If
transition
’s
initial snapshot containing block size
is not equal to the
snapshot containing block size
then
skip the view transition
for
transition
with an "
InvalidStateError
DOMException
in
transition
’s
relevant Realm
and return.
Update pseudo-element styles
for
transition
If failure is returned, then
skip the view transition
for
transition
with an "
InvalidStateError
DOMException
in
transition
’s
relevant Realm
and return.
Note:
The above implies that a change in incoming element’s size or position will cause a new keyframe to be generated.
This can cause a visual jump.
We could retarget smoothly but don’t have a use-case to justify the complexity.
See
issue 7813
for details.
7.9.
Update pseudo-element styles
To
update pseudo-element styles
for a
ViewTransition
transition
For each
transitionName
capturedElement
of
transition
’s
named elements
Let
width
height
transform
writingMode
direction
textOrientation
mixBlendMode
backdropFilter
and
colorScheme
be null.
If
capturedElement
’s
new element
is null, then:
Set
width
to
capturedElement
’s
old width
Set
height
to
capturedElement
’s
old height
Set
transform
to
capturedElement
’s
old transform
Set
writingMode
to
capturedElement
’s
old writing-mode
Set
direction
to
capturedElement
’s
old direction
Set
textOrientation
to
capturedElement
’s
old text-orientation
Set
mixBlendMode
to
capturedElement
’s
old mix-blend-mode
Set
backdropFilter
to
capturedElement
’s
old backdrop-filter
Set
colorScheme
to
capturedElement
’s
old color-scheme
Otherwise:
Return failure if any of the following conditions are true:
capturedElement
’s
new element
has a
flat tree
ancestor that
skips its contents
capturedElement
’s
new element
is
not rendered
capturedElement
has more than one
box fragment
Note:
Other rendering constraints are enforced via
capturedElement
’s
new element
being
captured in a view transition
Let
newRect
be the
snapshot containing block
if
capturedElement
’s
new element
is the
document element
otherwise,
capturedElement
’s
border box
Set
width
to the current width of
newRect
Set
height
to the current height of
newRect
Set
transform
to a transform that would map
newRect
from the
snapshot containing block origin
to its current visual position.
Set
writingMode
to the
computed value
of
writing-mode
on
capturedElement
’s
new element
Set
direction
to the
computed value
of
direction
on
capturedElement
’s
new element
Set
textOrientation
to the
computed value
of
text-orientation
on
capturedElement
’s
new element
Set
mixBlendMode
to the
computed value
of
mix-blend-mode
on
capturedElement
’s
new element
Set
backdropFilter
to the
computed value
of
backdrop-filter
on
capturedElement
’s
new element
Set
colorScheme
to the
computed value
of
color-scheme
on
capturedElement
’s
new element
If
capturedElement
’s
group styles rule
is null,
then set
capturedElement
’s
group styles rule
to a new
CSSStyleRule
representing the following CSS,
and append it to
transition
’s
relevant global object’s
associated document
’s
dynamic view transition style sheet
Otherwise, update
capturedElement
’s
group styles rule
to match the following CSS:
:root::view-transition-group
transitionName
width
width
height
height
transform
transform
writing-mode
writingMode
direction
direction
text-orientation
textOrientation
mix-blend-mode
mixBlendMode
backdrop-filter
backdropFilter
color-scheme
colorScheme
Note:
The above code example contains variables to be replaced.
If
capturedElement
’s
new element
is not null, then:
Let
new
be the
::view-transition-new()
with the
view transition name
transitionName
Set
new
’s
replaced element
content to the result of
capturing the image
of
capturedElement
’s
new element
This algorithm must be executed to update styles in
user-agent origin
if its effects can be observed by a web API.
Note:
An example of such a web API is
window.getComputedStyle(document.documentElement, "::view-transition")
7.10.
Clear view transition
To
clear view transition
of a
ViewTransition
transition
Let
document
be
transition
’s
relevant global object’s
associated document
Assert
document
’s
active view transition
is
transition
For each
capturedElement
of
transition
’s
named elements
values
If
capturedElement
’s
new element
is not null,
then set
capturedElement
’s
new element
’s
captured in a view transition
to false.
For each
style
of
capturedElement
’s
style definitions
If
style
is not null,
and
style
is in
document
’s
dynamic view transition style sheet
then remove
style
from
document
’s
dynamic view transition style sheet
Set
document
’s
show view transition tree
to false.
Set
document
’s
active view transition
to null.
Privacy Considerations
This specification introduces no new privacy considerations.
Security Considerations
The images generated using
capture the image
algorithm could contain cross-origin data (if the Document is embedding cross-origin resources) or sensitive information like visited links.
The implementations must ensure this data can not be accessed by the Document.
This should be feasible since access to this data should already be prevented in the default rendering of the Document.
Appendix A. Changes
This appendix is
informative
Changes from
2024-03-28 Candidate Recommendation Draft
Update wording to use
opacity: 0
instead of
visibility: hidden
. See
issue 12629
Always flush the queue of update callbacks before capturing the old state. See
issue 11922
Disallow
match-element
as a custom-ident. See
Issue 10995
Add a non-normative note to explain that
::view-transition-image-pair()
would typically not need custom styling. See
issue 11926
Inherit more animation properties into
pseudo-element tree
. See
Issue 11546
Use
position: absolute
instead of
position: fixed
on
::view-transition
. See
Issue 12116
Changes from
2023-05-30 Working Draft
Use a keyframe to add plus-lighter blending during cross-fade. See
issue 8924
Add mix-blend-mode to list of properties copied over to the
::view-transition-group
. See
issue 8962
Add text-orientation to list of properties copied over to the
::view-transition-group
. See
issue 8230
Refactor the old capture algorithm to properly set
captured in a view transition
before reading the value.
Make the
startViewTransition()
parameter non-nullable. See
issue 9460
Elements participating in a
view transition
are exposed to accessibility tree. See
issue 9365
The
view transition tree
is not exposed to accessibility tree. See
issue 9365
Animate back-drop filter similar to transform/size. See
issue 9358
Copy
color-scheme
from DOM element to
::view-transition-group()
. See
issue 9276
Expose auto-skip view transition for a
Document
, to allow having outbound cross-document transitions preceed programmatic view transiitons. see
issue 9512
Add a note about why
view-transition-name
should be animatable.
view-transition-name: auto
should be an invalid value. See
issue 9639
Add note to explain paint order for entry animations. See
issue 9672
Add note to explain how the named elements are cleaned up. See
issue 9669
Refactor algorithm to clarify timing, especially of `updateCallbackDone. See
issue 9762
Add animation-delay inherit to UA stylesheet rules for (::view-transition) -image-pair, -old, and -new. See
issue 9817
Auto-skip animation when document is hidden. See
issue 9543
Remove references to cross-document view-transitions, to keep the L1 spec clean. See
Issue 9886
Export an algorithm to skip the active transition when the page is hidden. See
issue 9543
Use snapshot containing block when capturing new state for document element. See
issue #10177
Fix algorithm for dispatching updateDOMCallback promise.
Scope view transition names to matching tree context. See
issue 10145
Fix scoping to match name instead of element. See
issue 10145
Add a rendering characteristics note about out-of-viewport elements. See
issue 8282
Swap the order of invoking the update callback and setting the phase. See
issue 10822
Changes from
2023-05-25 Working Draft
Fix typo in ::view-transition-new user agent style sheet. See
PR
Changes from
2022-11-24 Working Draft
Pointer events resolve to the documentElement when rendering is suppressed. See
issue 7797
Add rendering constraints to elements participating in a transition. See
issue 8139
and
issue 7882
Remove html specifics from UA stylesheet to support ViewTransitions on SVG Documents.
Rename updateDOMCallback to
ViewTransitionUpdateCallback
. See
issue 8144
Rename snapshot viewport to
snapshot containing block
Skip the transition if viewport size changes. See
issue 8045
Add support for :only-child. See
issue 8057
Add concept of a tree of
pseudo-elements
under
pseudo-element root
. See
issue 8113
When skipping a transition, the
ViewTransitionUpdateCallback
is called in own task rather than synchronously. See
issue 7904
When capturing images, at least the in-viewport part of the image should be captured, downscale if needed. See
issue 8561
Applying the
ink overflow
to the captured image is implementation defined, and doesn’t affect the image’s
natural size
. See
issue 8597
Fragmented elements don’t participate in view transitions. See
issue 8339
Rename "snapshot root" to "snapshot containing block", and make it an
absolute positioning containing block
and a
fixed positioning containing block
for its descendants. See
issue 8505
Changes from
2022-10-25 Working Draft (FPWD)
Add
dynamic view transition style sheet
concept for dynamically generated UA styles scoped to the current Document.
Add snapshot viewport concept. See
issue 7859
Clarify timing for resolving/rejecting promises when skipping the transition. See
issue 7956
Elements under a content-visibility:auto element that skips its contents are ignored. See
issue 7874
UA styles on the pseudo-DOM stay in sync with author DOM for any developer observable API. See
issue 7812
Suppress rendering during updateCallback. See
issue 7784
Changes in size/position of elements in the new Document generate new UA animation keyframes. See
issue 7813
Scope keyframes to user agent stylesheets using -ua- prefix. See
issue 7560
Update
pseudo-element
names to view-transition*. See
issue 7960
Update selector syntax for
pseudo-elements
. See
issue 7788
Add sections for security/privacy considerations.
Conformance
Document conventions
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:
This is an example of an informative example.
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

, like
this:
UAs MUST provide an accessible alternative.
Tests
Tests relating to the content of this specification
may be documented in “Tests” blocks like this one.
Any such block is non-normative.
Conformance classes
Conformance to this specification
is defined for three conformance classes:
style sheet
CSS
style sheet
renderer
UA
that interprets the semantics of a style sheet and renders
documents that use them.
authoring tool
UA
that writes a style sheet.
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.
Partial implementations
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.
Implementations of Unstable and Proprietary Features
To avoid clashes with future stable CSS features,
the CSSWG recommends
following best practices
for the implementation of
unstable
features and
proprietary extensions
to CSS.
Non-experimental implementations
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.
Further information on submitting testcases and implementation reports
can be found from on the CSS Working Group’s website at
Questions should be directed to the
public-css-testsuite@w3.org
mailing list.
Index
Terms defined by this specification
activate view transition
, in § 7.3
active view transition
, in § 7.1.1
call the update callback
, in § 7.4
captured element
, in § 7.1.3
captured in a view transition
, in § 7.1.2
capture rendering characteristics
, in § 7.7.1
capture the image
, in § 7.7
capture the new state
, in § 7.3.2
capture the old state
, in § 7.3.1
capturing the image
, in § 7.7
clear view transition
, in § 7.10

, in § 2.1
document-scoped view transition name
, in § 2.1
dynamic view transition style sheet
, in § 7.1.1
finished
, in § 6.2
finished promise
, in § 6.2
flush the update callback queue
, in § 7.4
global view transition user agent style sheet
, in § 5
group animation name rule
, in § 7.1.3
group keyframes
, in § 7.1.3
group styles rule
, in § 7.1.3
handle transition frame
, in § 7.8
image animation name rule
, in § 7.1.3
image pair isolation rule
, in § 7.1.3
initial snapshot containing block size
, in § 6.2
named elements
, in § 6.2
named view transition pseudo-elements
, in § 3.2.1
new element
, in § 7.1.3
none
, in § 2.1
old backdrop-filter
, in § 7.1.3
old color-scheme
, in § 7.1.3
old direction
, in § 7.1.3
old height
, in § 7.1.3
old image
, in § 7.1.3
old mix-blend-mode
, in § 7.1.3
old text-orientation
, in § 7.1.3
old transform
, in § 7.1.3
old width
, in § 7.1.3
old writing-mode
, in § 7.1.3
perform pending transition operations
, in § 7.2
phase
, in § 6.2
pseudo-element root
, in § 3.1
pseudo-element tree
, in § 3.1

, in § 3.2.1
ready
, in § 6.2
ready promise
, in § 6.2
rendering suppression for view transitions
, in § 7.1.1
schedule the update callback
, in § 7.4
setup transition pseudo-elements
, in § 7.3.3
setup view transition
, in § 7.3
show view transition tree
, in § 7.1.1
skip the view transition
, in § 7.5
skipTransition()
, in § 6.2.1
snapshot containing block
, in § 4.1
snapshot containing block origin
, in § 4.1
snapshot containing block size
, in § 4.1
startViewTransition()
, in § 6.1.1
startViewTransition(updateCallback)
, in § 6.1.1
style definitions
, in § 7.1.3
transition root pseudo-element
, in § 6.2
update callback
, in § 6.2
updateCallbackDone
, in § 6.2
update callback done promise
, in § 6.2
update callback queue
, in § 7.1.1
update pseudo-element styles
, in § 7.9
::view-transition
, in § 3.2.2
ViewTransition
, in § 6.2
::view-transition-group()
, in § 3.2.3
::view-transition-image-pair()
, in § 3.2.4
view transition layer
, in § 4.2
view transition name
, in § 2.1
view-transition-name
, in § 2.1
::view-transition-new()
, in § 3.2.6
::view-transition-old()
, in § 3.2.5
view transition page-visibility change steps
, in § 7.6
view transition pseudo-elements
, in § 3.2
view transitions
, in § 1
view transition tree
, in § 3.2
ViewTransitionUpdateCallback
, in § 6.1
Terms defined by reference
[]
defines the following terms:
NavigateEvent
signal
[COMPOSITING-2]
defines the following terms:
isolation
mix-blend-mode
[CSS-2022]
defines the following terms:
style sheet
[CSS-ANIMATIONS-1]
defines the following terms:
CSSKeyframesRule
[CSS-BACKGROUNDS-3]
defines the following terms:
canvas background
[CSS-BOX-4]
defines the following terms:
border box
content box
[CSS-BREAK-4]
defines the following terms:
box fragment
fragment
[CSS-CASCADE-5]
defines the following terms:
computed value
user-agent origin
[CSS-COLOR-4]
defines the following terms:
opacity
[CSS-COLOR-ADJUST-1]
defines the following terms:
color-scheme
[CSS-CONTAIN-2]
defines the following terms:
element contents
skips its contents
[CSS-DISPLAY-3]
defines the following terms:
containing block
replaced element
[CSS-DISPLAY-4]
defines the following terms:
initial containing block
principal box
root element
[CSS-IMAGES-3]
defines the following terms:
natural dimension
natural size
[CSS-IMAGES-4]
defines the following terms:
element-not-rendered
[CSS-MASKING-1]
defines the following terms:
clip-path
[CSS-OVERFLOW-3]
defines the following terms:
ink overflow
ink overflow area
ink overflow rectangle
overflow
scrollbar gutter
[CSS-POSITION-3]
defines the following terms:
absolute positioning containing block
fixed positioning containing block
[CSS-POSITION-4]
defines the following terms:
top layer
[CSS-PSEUDO-4]
defines the following terms:
tree-abiding pseudo-elements
[CSS-SHADOW-1]
defines the following terms:
flat tree
tree-scoped name
[CSS-SIZING-3]
defines the following terms:
height
width
[CSS-TRANSFORMS-1]
defines the following terms:
identity transform function
transform
[CSS-TRANSFORMS-2]
defines the following terms:

[CSS-UI-4]
defines the following terms:
pointer-events
[CSS-VALUES-4]
defines the following terms:

[CSS-VIEWPORT-1]
defines the following terms:
interactive-widget
[CSS-WRITING-MODES-3]
defines the following terms:
direction
[CSS-WRITING-MODES-4]
defines the following terms:
text-orientation
writing-mode
[CSS2]
defines the following terms:
element
stacking context
viewport
[CSSOM-1]
defines the following terms:
CSSStyleRule
[CSSOM-VIEW-1]
defines the following terms:
layout viewport
scrolling box
[DOM]
defines the following terms:
Document
Element
child
connected
descendant
document
document element
inclusive descendant
node document
parent
participate
root
shadow-including descendant
sibling
tree
[FILTER-EFFECTS-1]
defines the following terms:
filter
[FILTER-EFFECTS-2]
defines the following terms:
Backdrop Root
backdrop-filter
[GEOMETRY-1]
defines the following terms:
height
width
[HR-TIME-3]
defines the following terms:
duration
[HTML]
defines the following terms:
associated Document
child navigable
DOM manipulation task source
in parallel
queue a global task
relevant global object
relevant realm
relevant settings object
unhandledrejection
visibility state
[INFRA]
defines the following terms:
append
(for list)
append
(for set)
assert
contain
continue
exist
for each
(for list)
for each
(for map)
implementation-defined
list
map
set
struct
tuple
values
[INTERSECTION-OBSERVER]
defines the following terms:
IntersectionObserver
[POINTEREVENTS4]
defines the following terms:
pointer capture
[SCROLL-ANIMATIONS-1]
defines the following terms:
scroll-driven animations
[SELECTORS-3]
defines the following terms:
[SELECTORS-4]
defines the following terms:
:only-child
functional pseudo-element
originating element
originating pseudo-element
pseudo-elements
selector
type selector
ultimate originating element
[WEB-ANIMATIONS-1]
defines the following terms:
associated effect
discrete
document timeline
effect target
paused
pending animation event queue
play state
running
timeline
[WEBIDL]
defines the following terms:
AbortError
DOMException
Exposed
InvalidStateError
Promise
TimeoutError
a new promise
a promise resolved with
any
getter steps
invoke
mark as handled
method steps
react
reacting
reject
resolve
this
undefined
unrestricted double
References
Normative References
[COMPOSITING-2]
Compositing and Blending Module Level 2
. Editor's Draft. URL:
[CSS-2022]
Tab Atkins Jr.; Elika Etemad; Florian Rivoal.
CSS Snapshot 2022
. URL:
[CSS-ANIMATIONS-1]
David Baron; et al.
CSS Animations Level 1
. URL:
[CSS-BACKGROUNDS-3]
Elika Etemad; Brad Kemper.
CSS Backgrounds and Borders Module Level 3
. URL:
[CSS-BOX-4]
Elika Etemad.
CSS Box Model Module Level 4
. URL:
[CSS-BREAK-4]
Rossen Atanassov; Elika Etemad.
CSS Fragmentation Module Level 4
. URL:
[CSS-CASCADE-5]
Elika Etemad; Miriam Suzanne; Tab Atkins Jr..
CSS Cascading and Inheritance Level 5
. URL:
[CSS-COLOR-4]
Tab Atkins Jr.; Chris Lilley; Lea Verou.
CSS Color Module Level 4
. URL:
[CSS-COLOR-ADJUST-1]
Elika Etemad; et al.
CSS Color Adjustment Module Level 1
. URL:
[CSS-CONTAIN-2]
Tab Atkins Jr.; Florian Rivoal; Vladimir Levin.
CSS Containment Module Level 2
. URL:
[CSS-DISPLAY-3]
Elika Etemad; Tab Atkins Jr..
CSS Display Module Level 3
. URL:
[CSS-DISPLAY-4]
Elika Etemad; Tab Atkins Jr..
CSS Display Module Level 4
. URL:
[CSS-IMAGES-3]
Tab Atkins Jr.; Elika Etemad; Lea Verou.
CSS Images Module Level 3
. URL:
[CSS-IMAGES-4]
Elika Etemad; Tab Atkins Jr.; Lea Verou.
CSS Images Module Level 4
. URL:
[CSS-MASKING-1]
Dirk Schulze; Brian Birtles; Tab Atkins Jr..
CSS Masking Module Level 1
. URL:
[CSS-OVERFLOW-3]
Elika Etemad; Florian Rivoal.
CSS Overflow Module Level 3
. URL:
[CSS-POSITION-3]
Elika Etemad; Tab Atkins Jr..
CSS Positioned Layout Module Level 3
. URL:
[CSS-POSITION-4]
Elika Etemad; Tab Atkins Jr..
CSS Positioned Layout Module Level 4
. URL:
[CSS-PSEUDO-4]
Elika Etemad; Alan Stearns.
CSS Pseudo-Elements Module Level 4
. URL:
[CSS-SHADOW-1]
CSS Shadow Module Level 1
. Editor's Draft. URL:
[CSS-TRANSFORMS-1]
Simon Fraser; et al.
CSS Transforms Module Level 1
. URL:
[CSS-TRANSFORMS-2]
Tab Atkins Jr.; et al.
CSS Transforms Module Level 2
. URL:
[CSS-UI-4]
Tab Atkins Jr.; Florian Rivoal.
CSS Basic User Interface Module Level 4
. URL:
[CSS-VALUES-4]
Tab Atkins Jr.; Elika Etemad.
CSS Values and Units Module Level 4
. URL:
[CSS-VIEWPORT-1]
Florian Rivoal; Emilio Cobos Álvarez.
CSS Viewport Module Level 1
. URL:
[CSS-WRITING-MODES-3]
Elika Etemad; Koji Ishii.
CSS Writing Modes Level 3
. URL:
[CSS-WRITING-MODES-4]
Elika Etemad; Koji Ishii.
CSS Writing Modes Level 4
. URL:
[CSS2]
Bert Bos; et al.
Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification
. URL:
[CSSOM-1]
Daniel Glazman; Emilio Cobos Álvarez.
CSS Object Model (CSSOM)
. URL:
[CSSOM-VIEW-1]
Simon Fraser; Emilio Cobos Álvarez.
CSSOM View Module
. URL:
[DOM]
Anne van Kesteren.
DOM Standard
. Living Standard. URL:
[FILTER-EFFECTS-1]
Dirk Schulze; Dean Jackson.
Filter Effects Module Level 1
. URL:
[FILTER-EFFECTS-2]
Filter Effects Module Level 2
. Editor's Draft. URL:
[GEOMETRY-1]
Sebastian Zartner; Yehonatan Daniv.
Geometry Interfaces Module Level 1
. URL:
[HR-TIME-3]
Yoav Weiss.
High Resolution Time
. URL:
[HTML]
Anne van Kesteren; et al.
HTML Standard
. Living Standard. URL:
[INFRA]
Anne van Kesteren; Domenic Denicola.
Infra Standard
. Living Standard. URL:
[INTERSECTION-OBSERVER]
Stefan Zager; Emilio Cobos Álvarez; Traian Captan.
Intersection Observer
. URL:
[RFC2119]
S. Bradner.
Key words for use in RFCs to Indicate Requirement Levels
. March 1997. Best Current Practice. URL:
[SELECTORS-3]
Tantek Çelik; et al.
Selectors Level 3
. URL:
[SELECTORS-4]
Elika Etemad; Tab Atkins Jr..
Selectors Level 4
. URL:
[WEB-ANIMATIONS-1]
Brian Birtles; et al.
Web Animations
. URL:
[WEBIDL]
Edgar Chen; Timothy Gu.
Web IDL Standard
. Living Standard. URL:
Non-Normative References
[CSS-SIZING-3]
Tab Atkins Jr.; Elika Etemad.
CSS Box Sizing Module Level 3
. URL:
[POINTEREVENTS4]
Patrick Lauke; Robert Flack.
Pointer Events
. URL:
[SCROLL-ANIMATIONS-1]
Brian Birtles; et al.
Scroll-driven Animations
. URL:
Property Index
Name
Value
Initial
Applies to
Inh.
%ages
Anim­ation type
Canonical order
Com­puted value
view-transition-name
none |
none
all elements
no
n/a
discrete
per grammar
as specified
IDL Index
partial
interface
Document
ViewTransition
startViewTransition
optional
ViewTransitionUpdateCallback
updateCallback
);
};
callback
ViewTransitionUpdateCallback
Promise
any
> ();