[FEE-11104] View Transitions — Level 2 (Cross-document)
INFO
Add one CSS at-rule to every page in your multi-page site and the browser automatically animates between page navigations — no JavaScript, no SPA conversion, no framework required.
Limited Availability
Currently supported in Chrome 126+/Edge 126+ only. Firefox and Safari support is in progress. Check the MDN compatibility table before using in production.
Context
View Transitions Level 1 introduced document.startViewTransition() as a JavaScript API for animating DOM state changes within a single page. It solved the snapshot-timing race condition that made SPA transitions fragile. But Level 1 has an architectural boundary it cannot cross: the document boundary.
When the browser follows an <a href> link to a different URL, it destroys the current document's JavaScript execution context before the new document's JavaScript has any opportunity to run. The startViewTransition() call is only possible inside the live document — there is no JavaScript hook that straddles the gap between two documents. By the time the new page's scripts execute, the old page's pixel content is gone. The snapshot opportunity has passed.
This boundary is a fundamental property of the browser navigation model. It is not a limitation of the Level 1 API implementation — it is an architectural constraint on what any JavaScript API can do across a full-page navigation.
The consequence is that Multi-Page Application (MPA) architectures — sites built with plain HTML, Astro, VitePress, HTMX, or any server-rendered framework that produces real URL navigations — received no benefit from Level 1. Their navigations produced the familiar hard flash: old page disappears, new page appears, no animation.
The conventional workaround was to convert the MPA into a pseudo-SPA by intercepting link clicks in JavaScript, fetching the next page's HTML via fetch(), and swapping it into the DOM without a real navigation. This approach recovers the ability to call startViewTransition(), but at significant cost: the router must handle history management, scroll restoration, focus management, and progressive enhancement. Astro's <ClientRouter> and Swup.js both implement this pattern. For sites with hundreds of static pages, the infrastructure cost of SPA routing is often disproportionate to the benefit.
Level 2 addresses this at the platform level. Instead of requiring JavaScript to orchestrate the snapshot, Level 2 makes the snapshot machinery declarative: a CSS at-rule on both the outgoing and incoming page is enough for the browser to automatically wrap the navigation in the same snapshot-and-animate pipeline that Level 1 uses.
The result is that MPA transitions become a CSS concern rather than a JavaScript concern. No routing layer, no fetch interception, no history management — just a stylesheet entry on every page.
Why MPAs matter again in 2024–2026
The industry moved toward SPAs partly for the perceived UX benefit of smooth navigation. With Level 2, that benefit is available to MPAs without the complexity cost. Simultaneously, several forces are pushing developers back toward MPA architectures:
- Astro (static-site-first, zero JS by default) became the dominant choice for content-heavy documentation and marketing sites.
- VitePress powers most major open-source documentation sites (Vue, Vite, Vitest, Rollup, Pinia, and others).
- HTMX enables server-driven interactivity without client-side routing.
- Core Web Vitals favor server-rendered HTML for initial load performance.
Each of these architectures produces real navigations. Level 2 brings SPA-quality transitions to all of them.
Scenario
You are maintaining a documentation site built with plain HTML (or VitePress, or Astro). The site has a persistent site header with the product logo and navigation links. Currently, clicking between pages produces a hard flash: the old page disappears and the new page appears with no continuity.
You want to:
- Animate the page root with a smooth cross-fade on every navigation.
- Keep the site header visually continuous across navigations — it should appear to persist in place rather than flashing with the rest of the content.
- Respect
prefers-reduced-motion— users who have opted out of animations receive instant navigation. - Support browsers that do not implement Level 2 — they fall back to normal navigation without any error.
Requirements:
- No JavaScript changes.
- No SPA routing layer.
- Works for all same-origin navigations.
- Shipped CSS-only.
With View Transitions Level 2, all four requirements are met by two CSS blocks added to the global stylesheet.
Best Practices
MUST include
@view-transition { navigation: auto; }on both the outgoing and incoming page. The transition only fires when both documents have opted in. If either page is missing the at-rule — for example, an external page, a page you do not control, or a page that has not yet been updated — no transition fires and the navigation proceeds normally. This is a safe default: missing opt-in silently degrades to an instant navigation rather than breaking anything.MUST test with
@media (prefers-reduced-motion: reduce)and opt out of transitions for users who have requested it:css@media (prefers-reduced-motion: reduce) { @view-transition { navigation: none; } }Place this block alongside your
@view-transition { navigation: auto; }declaration in your global stylesheet. The media query takes precedence and overrides the at-rule for users who prefer reduced motion.SHOULD limit
view-transition-nameto elements that genuinely persist across navigations. A site header, a persistent navigation bar, or a hero image that appears on every page are appropriate candidates. Body content that changes completely between pages is not — giving it aview-transition-namewould produce a cross-fade of dissimilar content, which looks worse than the default root cross-fade.SHOULD NOT apply
view-transition-nameto elements with unpredictable DOM shapes across navigations. If the element exists on one page but not the other, the browser creates an unpaired snapshot and the result is either an unexpected fade-in or fade-out of content that was not intended to animate.MAY use
pageswapandpagerevealevents to dynamically assignview-transition-namefor list-to-detail shared transitions. For example, in a blog index, each article card could receive aview-transition-namematching its article ID just before navigation, so the card morphs into the article hero on the detail page:js// On the list page (outgoing): pageswap document.addEventListener('pageswap', (e) => { if (!e.viewTransition) return; const articleId = getNavigatingArticleId(); // derive from the target URL const card = document.querySelector(`[data-article-id="${articleId}"]`); if (card) { card.style.viewTransitionName = `article-${articleId}`; } }); // On the detail page (incoming): pagereveal document.addEventListener('pagereveal', (e) => { if (!e.viewTransition) return; const articleId = getArticleIdFromURL(); // derive from current URL const hero = document.querySelector('.article-hero'); if (hero) { hero.style.viewTransitionName = `article-${articleId}`; } });MAY use
sessionStorageto pass state from the outgoing page to the incoming page, sincepageswapandpagerevealrun in different documents. Write the navigating element's ID tosessionStorageinpageswap; read it inpagerevealto identify the correct element to name.SHOULD verify that cross-document transitions only fire for same-origin navigations. The browser enforces this automatically — cross-origin navigations never trigger cross-document view transitions regardless of opt-in status.
Design Thinking
Why the old document's JS context cannot be used
When the browser processes an <a href> click, the navigation lifecycle is:
- The current document's unload event fires.
- The current document's rendering context is torn down.
- The network request for the new URL begins (or the cached response is used).
- The new document is parsed and its scripts execute.
Step 2 happens before step 4. There is no way to coordinate snapshot timing across this gap using JavaScript, because neither document is alive at the same time. The old document's startViewTransition() would need the new document's "after" snapshot — but the new document has not rendered yet. The new document's startViewTransition() would need the old document's "before" snapshot — but the old document no longer exists.
This is not a missing API surface; it is a consequence of the browser's process model. Cross-origin navigations may switch to a new renderer process entirely, making shared memory or synchronization impossible.
The declarative model: CSS drives snapshot timing
Level 2 solves this by moving the opt-in mechanism to CSS and moving snapshot management into the browser's navigation infrastructure. The browser's navigation pipeline already has access to both the outgoing page (it controls when to tear it down) and the incoming page (it controls when to render it). By inserting snapshot capture points at those two moments, the browser can produce the before/after snapshots without any JavaScript coordination.
The @view-transition { navigation: auto; } at-rule is the signal that tells the browser: "when navigating away from or to this page, use the snapshot machinery." If both pages signal opt-in, the browser knows it is safe to:
- Capture the outgoing page's snapshot before tearing it down.
- Load and initialize the incoming page.
- Capture the incoming page's snapshot before first render.
- Animate between the two snapshots using the same pseudo-element tree as Level 1.
This is architecturally different from Level 1. Level 1 is imperative: the developer explicitly calls startViewTransition() and controls when it fires. Level 2 is declarative: the browser decides when to fire it, based on the presence of the CSS at-rule on both documents.
The declarative model is inherently more robust for navigations, because the browser has exact knowledge of when each document lifecycle phase occurs. The developer does not need to intercept clicks, manage promises, or coordinate across two execution contexts.
The pageswap and pagereveal events as escape hatches
The fully declarative path (CSS-only, no JS) works well for page-wide cross-fades and persistent-element morphs where the view-transition-name can be set statically in the stylesheet. However, some transitions require dynamic name assignment — specifically, list-to-detail transitions where the shared element differs on each navigation.
For this purpose, Level 2 introduces two new document events:
pageswap fires on the outgoing document, just before the final snapshot is taken. At this point, the outgoing document is still alive. The event's viewTransition property exposes the ViewTransition object for the navigation if a cross-document transition is about to fire, or null if not. Use pageswap to assign a view-transition-name to the element that is leaving.
pagereveal fires on the incoming document, before its first render. At this point, the new document's DOM is ready but nothing has been painted yet. Use pagereveal to assign a view-transition-name to the element that is arriving.
Both events receive the same ViewTransition object (accessed through the viewTransition property), which allows them to call viewTransition.skipTransition() if you decide at the last moment that this navigation should not animate.
These events fire for every same-origin cross-document navigation, not only navigations that have view transitions enabled. Always check e.viewTransition before manipulating names or making decisions based on transition state.
How Level 2 transitions compare to Level 1
The pseudo-element tree is identical. Once the cross-document transition is initiated, the browser creates the same overlay:
::view-transition
::view-transition-group(root)
::view-transition-image-pair(root)
::view-transition-old(root)
::view-transition-new(root)
::view-transition-group(site-header)
::view-transition-image-pair(site-header)
::view-transition-old(site-header)
::view-transition-new(site-header)All the CSS customization techniques from Level 1 — targeting ::view-transition-old and ::view-transition-new, writing custom @keyframes, using ::view-transition-group for morph animation — apply identically to Level 2 transitions.
The only difference is how the transition is initiated: Level 1 requires an explicit JS call, Level 2 fires automatically when both pages have opted in.
Navigation type filtering
The auto value triggers transitions on push, replace, and traverse navigations. A traverse navigation is a back/forward navigation through history. If you want to animate forward navigations but not back navigations — a common UX pattern — you can check e.viewTransition.navigationType in pageswap or pagereveal and call skipTransition() selectively.
Future Level 2 drafts include proposals for a types descriptor in @view-transition to enable CSS-level filtering without JavaScript, following the same pattern as @media queries for navigation type. Check the CSSWG draft for the current status.
Example
A two-page MPA documentation site. Both pages share the same stylesheet. The persistent site header morphs smoothly during navigation while the main content cross-fades.
page-a.html:
<!DOCTYPE html>
<html lang="en">
<head>
<style>
@view-transition {
navigation: auto;
}
@media (prefers-reduced-motion: reduce) {
@view-transition {
navigation: none;
}
}
header {
view-transition-name: site-header;
background: #1a1a2e;
color: white;
padding: 1rem 2rem;
display: flex;
align-items: center;
gap: 1rem;
}
header a {
color: #a8d8ea;
text-decoration: none;
}
main {
padding: 2rem;
max-width: 800px;
margin: 0 auto;
}
/* Optional: customize the root cross-fade duration */
::view-transition-old(root),
::view-transition-new(root) {
animation-duration: 0.3s;
}
</style>
</head>
<body>
<header>
<span>My Documentation Site</span>
<nav>
<a href="page-a.html">Introduction</a>
<a href="page-b.html">Chapter 1</a>
</nav>
</header>
<main>
<h1>Introduction</h1>
<p>Welcome to the documentation. This is page A.</p>
<p><a href="page-b.html">Go to Chapter 1 →</a></p>
</main>
</body>
</html>page-b.html (identical stylesheet, different content — the header persists visually):
<!DOCTYPE html>
<html lang="en">
<head>
<style>
@view-transition {
navigation: auto;
}
@media (prefers-reduced-motion: reduce) {
@view-transition {
navigation: none;
}
}
header {
view-transition-name: site-header;
background: #1a1a2e;
color: white;
padding: 1rem 2rem;
display: flex;
align-items: center;
gap: 1rem;
}
header a {
color: #a8d8ea;
text-decoration: none;
}
main {
padding: 2rem;
max-width: 800px;
margin: 0 auto;
}
::view-transition-old(root),
::view-transition-new(root) {
animation-duration: 0.3s;
}
</style>
</head>
<body>
<header>
<span>My Documentation Site</span>
<nav>
<a href="page-a.html">Introduction</a>
<a href="page-b.html">Chapter 1</a>
</nav>
</header>
<main>
<h1>Chapter 1</h1>
<p>This is the first chapter. The header above persisted from the previous page.</p>
<p><a href="page-a.html">← Back to Introduction</a></p>
</main>
</body>
</html>What happens on navigation
When the user clicks "Go to Chapter 1":
- The browser recognizes the navigation as same-origin.
- It checks the outgoing page (
page-a.html) for@view-transition { navigation: auto; }— present. - It fires
pageswapon the outgoing document. Anypageswaplistener can adjustview-transition-nameassignments at this point. - The browser captures the "before" snapshots:
site-header(the persistent header) androot(the full page). - The browser loads
page-b.htmland parses its DOM. - It checks the incoming page for
@view-transition { navigation: auto; }— present. - It fires
pagerevealon the incoming document before first render. - The browser captures the "after" snapshots:
site-header(the header on page B, same position and size) androot. - The transition animates:
site-headermorphs in place (since it is the same size and position, it is essentially a cross-fade at the same location), whilerootcross-fades the changed body content.
Because the header is the same height, background color, and position on both pages, the site-header morph is invisible — it looks as if the header never moved. Only the main content area cross-fades, giving the impression of persistent navigation.
Shared element morph across pages using pageswap / pagereveal
For a blog with an article list page and article detail pages, the article card can morph into the article hero image:
// Shared utility: derive article ID from a URL string
function getArticleIdFromHref(href) {
const url = new URL(href, location.href);
return url.searchParams.get('id') || url.pathname.split('/').pop();
}
// On the list page: assign name to the clicked card before snapshot
document.addEventListener('pageswap', (e) => {
if (!e.viewTransition) return;
// Note: :focus/:active may already be cleared at pageswap time.
// For production use, capture the target in a click handler instead.
const link = document.querySelector('a:focus, a:active');
if (!link) return;
const articleId = getArticleIdFromHref(link.href);
const card = document.querySelector(`[data-id="${articleId}"] img`);
if (card) {
card.style.viewTransitionName = `article-hero-${articleId}`;
}
});// On the detail page: assign name to the hero image before first render
document.addEventListener('pagereveal', (e) => {
if (!e.viewTransition) return;
const articleId = document.querySelector('article').dataset.id;
const hero = document.querySelector('.hero-image');
if (hero && articleId) {
hero.style.viewTransitionName = `article-hero-${articleId}`;
}
});The view-transition-name values on both sides match (article-hero-${articleId}), so the browser pairs the outgoing card image with the incoming hero image and produces a morph animation across the navigation boundary.
Reliability of :focus and :active in pageswap
The a:focus, a:active selector used above is a simplified example. By the time pageswap fires, the browser may have already cleared :focus and :active states on the triggering anchor, so this query can silently return null. For production use, the sessionStorage pattern shown in the next section is the recommended approach: capture the target element (or its identifier) in a click handler before navigation begins, then read it back in pageswap or pagereveal.
Customizing the cross-fade with keyframes
The default root transition is a 300ms cross-fade. To replace it with a directional slide:
@keyframes slide-from-right {
from {
opacity: 0;
transform: translateX(40px);
}
}
@keyframes slide-to-left {
to {
opacity: 0;
transform: translateX(-40px);
}
}
::view-transition-old(root) {
animation: slide-to-left 0.3s ease-in forwards;
}
::view-transition-new(root) {
animation: slide-from-right 0.3s ease-out forwards;
}
@media (prefers-reduced-motion: reduce) {
@view-transition {
navigation: none;
}
}This works identically to Level 1 keyframe customization. The pseudo-elements behave the same way regardless of whether the transition was initiated by startViewTransition() or by the cross-document opt-in.
Using sessionStorage to pass state across the navigation boundary
Because pageswap and pagereveal fire in different documents, they do not share JavaScript variables. Use sessionStorage to pass a small piece of state:
// pageswap: record which article the user clicked
document.addEventListener('pageswap', (e) => {
if (!e.viewTransition) return;
const link = document.querySelector('a:focus');
if (link) {
const id = getArticleIdFromHref(link.href);
sessionStorage.setItem('transitioningArticleId', id);
}
});
// pagereveal: read the value and assign the name
document.addEventListener('pagereveal', (e) => {
if (!e.viewTransition) return;
const id = sessionStorage.getItem('transitioningArticleId');
sessionStorage.removeItem('transitioningArticleId');
if (!id) return;
const hero = document.querySelector('.hero-image');
if (hero) {
hero.style.viewTransitionName = `article-hero-${id}`;
}
});This pattern works because sessionStorage persists across same-origin navigations within the same browser tab.
Feature detection
Cross-document view transitions do not require a JavaScript feature check because they degrade silently. If the browser does not support Level 2, the @view-transition at-rule is ignored and normal navigation proceeds. No JavaScript error, no layout break.
However, if you are writing pageswap or pagereveal listeners, include a guard on e.viewTransition to avoid null reference errors in browsers that fire the events but do not populate the viewTransition property:
document.addEventListener('pagereveal', (e) => {
if (!e.viewTransition) return; // safely exits on unsupported browsers
// ...
});For CSS-only usage (no pageswap/pagereveal), no additional feature detection is needed.
Browser Support
| Browser | Cross-Document View Transitions | Notes |
|---|---|---|
| Chrome | 126 | Main frame navigations; iframe support added later |
| Edge | 126 | Chromium-based |
| Firefox | In progress | Under active development; not yet shipped |
| Safari | In progress | Under active development; not yet shipped |
The pageswap and pagereveal events are available in Chrome 126+ and Edge 126+. Both events fire for same-origin cross-document navigations regardless of whether a view transition is active.
Cross-document view transitions are expected to reach Baseline once Firefox and Safari ship support. Monitor the MDN compatibility table for current status.
CSS @supports cannot reliably feature-detect cross-document view transitions because the @view-transition at-rule is parsed by browsers that do not implement navigation-based transitions (they may support the at-rule for other reasons). The safest production pattern is to include the at-rule unconditionally and let non-supporting browsers ignore it.
Internal References
- FEE-11103 View Transitions — Level 1 — Prerequisite reading. Covers
document.startViewTransition(), the pseudo-element tree (::view-transition-old,::view-transition-new,::view-transition-group), snapshot timing, and the FLIP problem. Level 2 reuses all of these concepts; the pseudo-element tree is identical for cross-document transitions.
References
- Cross-document view transitions for multi-page applications — Chrome for Developers
- @view-transition — MDN Web Docs
- View Transition API — MDN Web Docs
- Using the View Transition API — MDN Web Docs
- What's new in view transitions? (Google I/O 2024 update) — Chrome for Developers
- CSS View Transitions Module Level 2 — CSSWG Editors Draft
- cross-doc-explainer.md — WICG/view-transitions on GitHub
- Smooth transitions with the View Transition API — Chrome for Developers