· 6 min read
Cross-document view transitions: animate page navigations
Cross-document view transitions animate navigations in multi-page sites with one CSS rule. How opt-in, shared elements, types and pagereveal work.

Cross-document view transitions animate the change from one page to another in a normal multi-page site, with no client-side router and no JavaScript required. You add @view-transition { navigation: auto; } to the CSS of both pages, and same-origin navigations between them cross-fade instead of flashing white. Give matching elements on each page the same view-transition-name, and the browser morphs one into the other.
It works in Chrome and Edge from version 126 and in Safari from 18.2. Firefox support is partial at the time of writing, which is fine, because browsers that don't support it just navigate normally.
What are cross-document view transitions?
A view transition is a browser-managed animation between two visual states of a page. The browser takes a snapshot of the old state, renders the new state, and animates between them using pseudo-elements you can style with CSS.
The first version of the API only worked inside one document: you called document.startViewTransition() in a single-page app and updated the DOM in a callback. Cross-document view transitions extend the same idea to real navigations, where one HTML document is unloaded and another is loaded. That is the part that matters for multi-page apps (MPAs), static sites, server-rendered pages and anything built with plain links.
The snapshot of the old page is a static image. The new page is live, so its content keeps rendering while the animation runs.
How do you turn on view transitions between pages?
Put this in a stylesheet that both the current page and the destination page load:
@view-transition {
navigation: auto;
}
That is the whole opt-in. Both documents have to opt in, which is why a shared global stylesheet is the natural home for it. The default animation is a cross-fade of the whole page: the old snapshot fades out while the new page fades in.
The browser only runs the transition when a few conditions hold:
- The two documents are same-origin. Navigating to another site never triggers one.
- There is no cross-origin redirect anywhere in the chain.
- The navigation type is
push,replaceortraverse. Traverse covers back and forward. - For
pushandreplace, the navigation was started by the user interacting with the page, such as clicking a link or submitting a form, not by browser UI like typing in the address bar.
If any of those fail, the navigation still happens. It just isn't animated. Setting navigation: none on a page opts it out explicitly.
How do you animate specific elements between pages?
The page-wide cross-fade is pleasant but generic. The interesting effect is shared-element transitions, where a thumbnail on a list page grows into the hero image on the detail page.
You do this by giving the element the same view-transition-name on both pages:
/* list page */
.card[data-id="42"] img {
view-transition-name: product-42;
}
/* detail page */
.hero img {
view-transition-name: product-42;
}
The browser captures each named element separately, then animates its size and position from the old box to the new box while cross-fading the two images. Everything without a name falls under the default root name, which the browser assigns to :root.
Names must be unique among rendered elements at the moment of capture. If two visible elements share a name, the transition is skipped. On a list page, that usually means setting the name inline per item, or only on the item that was clicked.
The animation is built from a tree of pseudo-elements:
::view-transition
└─ ::view-transition-group(product-42)
└─ ::view-transition-image-pair(product-42)
├─ ::view-transition-old(product-42)
└─ ::view-transition-new(product-42)
You style these like any other element. For cross-document transitions, the styles need to be in the destination document, because that is where the animation runs. If you want the same effect going back, include them on both pages.
::view-transition-group(product-42) {
animation-duration: 300ms;
animation-timing-function: ease-out;
}
How do you customize a transition per navigation?
Two events let you adjust a transition from either side of the navigation:
pageswapfires on the old page just before it unloads. ItsviewTransitionproperty is the transition object, ornullif there isn't one, and itsactivationproperty describes the navigation, including the destination URL.pagerevealfires on the new page when it is first rendered, whether it came from the network, the back/forward cache or a prerender. It also has aviewTransitionproperty.
A common use is labelling the transition so CSS can pick a different animation. View transition types are string labels attached to a running transition, and :active-view-transition-type() matches while a transition with that type is in progress.
// On the new page
window.addEventListener('pagereveal', (e) => {
if (!e.viewTransition) return;
const from = navigation.activation?.from?.url;
if (from && new URL(from).pathname.startsWith('/products/')) {
e.viewTransition.types.add('back-to-list');
}
});
/* slide-out-right and slide-in-left are your own @keyframes */
html:active-view-transition-type(back-to-list)::view-transition-old(root) {
animation-name: slide-out-right;
}
html:active-view-transition-type(back-to-list)::view-transition-new(root) {
animation-name: slide-in-left;
}
You can also declare static types right in the opt-in with @view-transition { navigation: auto; types: slide; }. And you can call e.viewTransition.skipTransition() in either event when a particular navigation shouldn't animate.
How do you keep page transitions fast and accessible?
A cross-document transition can only start once the new page has something worth showing. If the browser renders too early, the named element may not exist yet and the effect falls apart. You can hold the first render until a specific element has been parsed:
<head>
<link rel="expect" href="#hero" blocking="render">
</head>
rel="expect" with blocking="render" tells the browser not to paint until the element with id="hero" is in the DOM. It has to be in the <head>. Use it for the one or two elements the transition depends on, not the whole page; every render-blocking hint delays first paint.
Motion is the other consideration. Some users ask their operating system to reduce motion, and a sliding page can be uncomfortable. The simplest approach is to opt in only when that preference isn't set:
@media (prefers-reduced-motion: no-preference) {
@view-transition {
navigation: auto;
}
}
Finally, treat the whole feature as progressive enhancement, the same way you would treat newer layout features like CSS anchor positioning. Nothing breaks in a browser that ignores the at-rule.
| Browser | Cross-document view transitions |
|---|---|
| Chrome, Edge | Supported from 126 |
| Safari (macOS and iOS) | Supported from 18.2 |
| Firefox | Partial support in recent versions |
Key takeaways
@view-transition { navigation: auto; }on both pages animates same-origin navigations with a cross-fade.- Matching
view-transition-namevalues on two pages create shared-element morphs; names must be unique at capture time. - Put transition pseudo-element styles in the destination page, or on both pages for two-way effects.
- Use
pageswap,pagerevealand view transition types to vary the animation by navigation. - Hold rendering with
<link rel="expect" blocking="render">only for elements the transition needs, and respect reduced motion.
FAQ
Do cross-document view transitions need JavaScript?
No. The opt-in, named elements and custom animations are all CSS. JavaScript is only needed if you want to change the transition per navigation using pageswap or pagereveal.
Do they work across different domains?
No. Both documents must be same-origin, and a cross-origin redirect in between cancels the transition. The navigation itself still completes normally.
What happens in browsers without support?
The @view-transition rule is ignored and links navigate the way they always have. There is no fallback to write.