Cross-Document View Transitions: Browser Support, MPA

What are Cross-Document View Transitions?

Cross-document view transitions are a feature of the W3C View Transitions Module Level 2 specification. The browser snapshots the old and new pages on a same-origin navigation, suppresses rendering while the DOM swaps, and animates between the snapshots using CSS, with no JavaScript required.

Which browsers support Cross-Document View Transitions?

Cross-document view transitions ship by default in every major Chromium release and in WebKit, with Firefox still working on its implementation. Global support sits near 85% of tracked browser usage.

How do cross-document view transitions work?

A same-origin link click on a page that opted in with @view-transition runs through a five-stage pipeline. The browser drives every stage; the page only declares names and timing in CSS.

• Snapshot the old page: The browser captures the current document and any element with a unique view-transition-name as a static snapshot, then fires pageswap on the outgoing page so a script can customize the transition.
• Suppress rendering: The browser holds painting on the old document while the navigation request resolves, so the user does not see a white flash between pages.
• Load the new page: The destination document parses, runs its render-blocking dependencies, and fires pagereveal once it is ready to display, exposing the same viewTransition object to the incoming script.
• Pair the snapshots: Elements that share the same view-transition-name on the old and new pages are matched, and CSS pseudo-elements like ::view-transition-old and ::view-transition-new are generated for each pair.
• Animate with CSS: The default cross-fade plays unless the page defines @keyframes on the pseudo-elements, then the browser swaps the snapshots for the live new document and removes the transition root.

How do you enable cross-document view transitions?

Two CSS lines on each page are enough to opt in. The trigger is the navigation itself, so no JavaScript call is required.

• Serve both pages on the same origin: Confirm the source URL and the destination URL share the same scheme, host, and port. A cross-origin navigation skips the transition silently.
• Add the @view-transition at-rule: Drop @view-transition { navigation: auto; } into a stylesheet that loads on both pages, so each document opts in to same-origin transitions.
• Tag shared elements with view-transition-name: Give a header, hero image, or product card the same view-transition-name on both pages so the browser pairs the snapshots and morphs them instead of cross-fading.
• Customize with pageswap or pagereveal if needed: Listen for the pageswap event on the outgoing page or pagereveal on the incoming page to set transition types, swap names per navigation, or call skipTransition for back-button navigations.
• Confirm the transition fires: Open Chrome 126, Edge 126, or Safari 18.2 on macOS or iOS, navigate between two opted-in pages, and watch the cross-fade or shared-element morph play before the new page settles.

A minimal opt-in plus a custom slide animation looks like the snippet below, applied identically on both pages.

/* Opt the document in to same-origin cross-document transitions. */
@view-transition {
  navigation: auto;
}

/* Pair a hero image across the two pages. */
.hero-image {
  view-transition-name: hero;
}

/* Slide the old page out, slide the new page in. */
::view-transition-old(root) {
  animation: 240ms ease-out both slide-out;
}
::view-transition-new(root) {
  animation: 240ms ease-out both slide-in;
}

@keyframes slide-out {
  to { transform: translateX(-24px); opacity: 0; }
}
@keyframes slide-in {
  from { transform: translateX(24px); opacity: 0; }
}

If the animation does not play, the navigation is probably cross-origin or the destination page is missing the @view-transition at-rule. Both documents must opt in.

What are the use cases of cross-document view transitions?

The feature unlocks SPA-style polish for traditional multi-page apps without rewriting a stack onto a client-side router. The patterns below are the highest-value wins for content sites, ecommerce, and documentation.

• Product list to product detail: Tag the thumbnail on the listing page and the hero image on the detail page with the same view-transition-name to morph one image into the other while the page swaps. Ecommerce sites use this to keep visual context across the funnel.
• Documentation chapter navigation: Cross-fade the article body while a persistent sidebar and header stay still, so a docs site reads like an SPA but ships as static HTML.
• Blog index to post: Morph the post card title into the article H1 when a reader clicks through, and let the rest of the page cross-fade.
• Wizard and checkout flows: Slide step 1 out and step 2 in on a multi-page checkout, giving a guided-flow feel without a JavaScript router.
• Marketing site polish: Animate the navigation between landing pages, pricing, and feature pages so the site feels app-like to first-time visitors.
• Dark-mode swap on navigation: Pair the @view-transition at-rule with a transition type set in pageswap to play a different animation when the user toggles a theme that lives on a separate page.

What are the known issues with cross-document view transitions?

The API is opt-in and degrades cleanly, but a handful of cross-engine quirks still bite real projects. The common pain points cover Firefox, cross-origin navigation, render-blocking timing, and the back/forward cache.

• Firefox is missing in stable: Firefox does not run cross-document transitions by default, so a portion of users never see the animation. The fallback is a normal navigation, which is acceptable for progressive enhancement but breaks any flow that depends on the visual continuity.
• Same-origin only: A navigation from www.example.com to checkout.example.com is treated as cross-origin and skips the transition, since the host differs. Subdomain-spanning flows need a same-origin redirect or a single host.
• Render-blocking timing matters: If the destination page paints late, the browser may time out the suppressed render and play a default cross-fade against a half-loaded view. Use the <link rel="expect"> pattern to hold the reveal until critical content is parsed.
• Back/forward cache interaction: A bfcache restore fires pageshow, not pagereveal, and the browser may skip the transition entirely. Customizations that rely on pagereveal need a pageshow fallback for back-button navigations.
• Duplicate view-transition-name values: If two elements on the same page share the same view-transition-name, the browser drops the entire transition. Generate unique names from a stable id, especially in lists.
• Print and reduced motion: Browsers honor prefers-reduced-motion by skipping the animation. The page still navigates, but designers should not rely on the morph for critical wayfinding.

In my experience, the silent killer is the same-origin rule on subdomain-heavy stacks. A morph that runs perfectly in local dev on localhost stops firing the moment staging splits the marketing site and the app onto two subdomains, and the bug looks like a missing CSS file. Always test the navigation between the actual production hosts before sign-off.

Citations

All cross-document view transitions version numbers and platform notes in this guide come from these primary sources:

• W3C - CSS View Transitions Module Level 2: drafts.csswg.org/css-view-transitions-2
• MDN Web Docs - View Transition API: developer.mozilla.org/en-US/docs/Web/API/View_Transition_API
• MDN Web Docs - @view-transition at-rule: developer.mozilla.org/en-US/docs/Web/CSS/@view-transition
• Chrome for Developers - Cross-document view transitions: developer.chrome.com/docs/web-platform/view-transitions/cross-document
• WebKit Blog - Two lines of cross-document view transitions: webkit.org/blog/16967
• WICG - Cross-document view transitions explainer: github.com/WICG/view-transitions/blob/main/cross-doc-explainer.md
• Chrome Platform Status - View Transitions cross-document: chromestatus.com/feature/5160002255847424
• Apple Developer - Safari 18.2 release notes: developer.apple.com/documentation/safari-release-notes/safari-18_2-release-notes
• Mozilla Hacks - CSS category: hacks.mozilla.org/category/css
• W3C - CSS Working Group: w3.org/Style/CSS