Skip to content

Cross-document view transitions: animate between pages with CSS

From the work/ 10 min read

Cross-document view transitions with only CSS: the product photo travels from the list to the detail page, custom timing, reduced motion and what happens without support.

  • Performance
  • JavaScript
In this article (9)
  1. What cross-document view transitions do
  2. Turn them on with @view-transition { navigation: auto }
  3. view-transition-name for the product photo
  4. Customize the animation
  5. Respect prefers-reduced-motion
  6. What happens without support
  7. Common mistakes
  8. Frequently asked questions
  9. Checklist

Cross-document view transitions animate the move from one page to another on the same site, with no library and no JavaScript. Add @view-transition { navigation: auto; } to the CSS of both pages and give the product photo the same view-transition-name on the list and on the detail page: the browser moves and scales it.

Below is the full example of a product list and its detail page, how to change the duration and easing, how to respect people who asked for less motion, and what a browser without support shows. We tested both pages locally with Playwright in Chromium, WebKit and Firefox.

What cross-document view transitions do

On a multi-page site, every click loads a new document and the screen swaps at once. A cross-document transition makes the browser take a snapshot of the outgoing page, load the new one and animate from one to the other. By default it is a cross-fade of the whole page. If you also mark an element with the same name on both pages, that element travels: it changes position and size from where it was to where it lands.

For a store, that is the useful part: the photo on the collection card grows into the large photo on the product page, and the shopper sees it is the same product. You do not need to turn the site into a SPA or load an animation framework. It works with HTML served by any backend: a theme, a static site or server-rendered pages.

There are conditions. Per MDN, the navigation must be same-origin, with no cross-origin redirects along the way, and of type push, replace or traverse (back and forward). push and replace only count when the user starts them from the page content, not from the browser UI. The Chrome documentation spells it out: typing in the address bar, opening a bookmark or reloading does not trigger a transition, and if the new page takes more than four seconds, Chrome skips it with a TimeoutError.

Turn them on with @view-transition { navigation: auto }

Opting in is a CSS rule. Both pages, the one you leave and the one you land on, must have it; if only one does, there is no transition. The simplest place is the stylesheet they share:

/* styles.css: both pages load it */
@view-transition {
  navigation: auto;
}
  1. The comment states what matters: the rule must be in the CSS of both pages.
  2. @view-transition is an at-rule that configures the document's transitions.
  3. navigation: auto asks for a transition when navigating to another same-origin page and the conditions above hold. The other value, none, turns it off.

That alone gives you a cross-fade between pages. The rule also accepts a types descriptor, which tags the transition so you can style different cases differently; you do not need it to start.

view-transition-name for the product photo

To make the photo travel, give it the same name on the list and on the detail page with view-transition-name. Each product needs its own name, because two elements on the same page cannot share one:

<!-- index.html: the list -->
<a href="/producto-42.html">
  <img src="/taza.svg" alt="Blue ceramic mug" width="160" height="160"
       style="view-transition-name: producto-42">
  Blue mug
</a>

<!-- producto-42.html: the detail page -->
<img src="/taza.svg" alt="Blue ceramic mug" width="480" height="480"
     style="view-transition-name: producto-42">
<h1>Blue mug</h1>
  1. On the list, each card links to its detail page. It is a plain link: no onclick, no fetch.
  2. The card image carries view-transition-name: producto-42, generated in your template from the product ID or handle. The next card gets producto-43, and so on.
  3. On the detail page, the large photo carries the same name. The browser pairs the two snapshots by that name and animates position and size from one to the other.
  4. Both images have width and height, so their box has its final size from the first render.

The name is a CSS identifier: it cannot start with a digit. We checked with CSS.supports: producto-42 is valid, 42 is not. If you use the numeric product ID, give it a prefix.

If your product card already adapts with container queries, the name goes on its image and nothing else changes. And the dimensions are not a detail: they are the same rule that prevents the layout jump we covered in fixing CLS from a cookie banner. The transition ends where the photo's box sits on the new page; if that box resizes when the image arrives, you will see it.

the photo travels from the list to the product pagelist · index.htmlproducto-42detail · producto-42.htmlproducto-42the same view-transition-name on both pagesthe browser animates size and positionno JavaScript: two HTML pages and a few lines of CSS

Scroll the figure sideways to see all of it

In our test, every card on the list had its own name. The producto-43 card does not exist on the detail page, so the browser fades it out separately, as its own group. Each name is one more snapshot; if your collection shows a hundred products at once, consider naming only the clicked card from the pageswap event, as in the MDN example.

Customize the animation

During the transition, the browser builds a tree of pseudo-elements on top of the page. ::view-transition is the overlay that covers everything. Inside it there is one ::view-transition-group() per name, plus the root one, which is the rest of the page. Each group holds a ::view-transition-image-pair() with two snapshots: ::view-transition-old(), a static image of the outgoing page, and ::view-transition-new(), a live view of the incoming one.

the pseudo-elements a transition creates::view-transitionoverlay on top of the whole page::view-transition-group(root)animates size and position::view-transition-image-pair(root)isolates the two snapshots' blend::view-transition-old(root)static snapshot of the old page::view-transition-new(root)live view of the new page::view-transition-group(producto-42)one group per nameimage-pair, old and new with that namethe same structurestyle them with CSS: animation-duration, timing, keyframesold and new inherit the group's timingdefault: 0.25s and a cross-fade

Scroll the figure sideways to see all of it

The group animates size and position; the snapshots do the fade. Per the browser stylesheet in the specification, the group lasts 0.25s and the snapshots inherit that animation. Since they are pseudo-elements, you change them with regular animation properties:

::view-transition-group(*) {
  animation-duration: 350ms;
  animation-timing-function: cubic-bezier(0.2, 0, 0, 1);
}

::view-transition-old(root),
::view-transition-new(root) {
  animation-duration: 200ms;
}
  1. ::view-transition-group(*) targets every group: the photo and the rest of the page.
  2. animation-duration: 350ms lengthens the photo's trip. The snapshots in each group inherit that duration.
  3. The cubic-bezier(0.2, 0, 0, 1) curve starts fast and slows at the end, so the photo settles without a bounce.
  4. The second block shortens only the root fade to 200ms, so the rest of the page changes before the photo lands.

We checked the timings with document.getAnimations() in Chromium and WebKit: the producto-42 group ran for 350ms and the root fade for 200ms. For your own effects, such as sliding the page, define @keyframes and assign them with animation-name to ::view-transition-old(root) and ::view-transition-new(root).

Respect prefers-reduced-motion

Some people ask their operating system for less motion because large animations make them dizzy or distract them. CSS exposes that preference through prefers-reduced-motion. The Chrome documentation suggests turning off the pseudo-element animations with that query, and notes that reduced motion does not mean no motion. You have two options, and we tested both.

Option A: opt in only when there is no preference. People who asked for less motion navigate as usual, unanimated:

@media (prefers-reduced-motion: no-preference) {
  @view-transition {
    navigation: auto;
  }
}

Option B: keep the transition but drop the travel. The groups no longer move or resize, and a fade remains:

@view-transition {
  navigation: auto;
}

@media (prefers-reduced-motion: reduce) {
  ::view-transition-group(*) {
    animation-name: none;
  }
}
  1. In option A, the @view-transition rule lives inside the query. With the reduce preference on, there is no transition: in our test, pagereveal arrived with no transition.
  2. In option B, the transition always exists and the query only removes the group animation. The snapshots keep their own fade animation.
  3. With the preference on, the option B test showed only the fade animations and no group animation.

For a store, option A is the safer choice: the fade carries no information, and people who asked for less motion lose nothing.

What happens without support

This is the good part: if the browser does not understand @view-transition, it ignores the rule and navigates as usual. No feature detection, no polyfill. In our test, Firefox opened the detail page and went back with no console errors and no transition. Support as of November 19, 2026, per MDN's compatibility data and the Chrome documentation:

BrowserCross-documentSame-document
Chrome126111
Edge126111
Safari (macOS and iOS)18.218
FirefoxNot in the stable release (MDN marks it as preview)144

The same-document column is the other half of the API, document.startViewTransition(), for changes inside a single document. MDN marks @view-transition as limited availability, and view-transition-name as Baseline since October 2025, because of that half.

view transitions support, November 19, 2026browsercross-documentsame-documentChrome126111Edge126111Safari (macOS, iOS)18.218Firefoxno (preview only)144without support, navigation works the same, unanimatedtested: Chromium 151, WebKit 26.5 and Firefox 155a progressive enhancementsources: MDN and developer.chrome.com

Scroll the figure sideways to see all of it

One detail from our test: in headless Chromium, when the detail page's photo was not cached, the new page skipped the transition on some loads, logging "Transition was skipped" (3 out of 8). With the images cached it passed 12 out of 12, and WebKit passed 8 out of 8. We did not check it in a windowed Chrome, but if the animation only fails sometimes, look at image caching first.

To know whether the transition ran, listen for the pagereveal event on the new page. Chrome has it since 124 and Safari since 18.2; in a browser without it, the event never fires and nothing breaks:

addEventListener("pagereveal", (e) => {
  console.log(e.viewTransition ? "with transition" : "no transition");
});
  1. pagereveal fires on the new page before its first render.
  2. e.viewTransition is the transition object, or null when there is none.

Common mistakes

  • Putting the rule on one page only. Both need @view-transition; otherwise there is no transition.
  • Repeating a name on the same page. With two producto-42, Chromium logs "Unexpected duplicate view-transition-name: producto-42" and aborts the transition. Watch out for "related products" on the detail page.
  • Using the bare ID as the name. 42 is not a valid identifier; use producto-42.
  • Images without dimensions. The photo travels toward a box that resizes when the image arrives.
  • Testing by reloading. Reloading, typing the URL or opening a bookmark does not trigger a transition; test by clicking a link.
  • Expecting it across domains. It only works on the same origin, with no cross-origin redirects along the way.
  • Long animations. The new page is usable during the animation, but a one-second transition feels slow on every click.
  • Ignoring people who asked for less motion. Wrap the opt-in in prefers-reduced-motion.

Frequently asked questions

Do I need JavaScript for cross-document view transitions?

No. The opt-in and the animation are CSS, and view-transition-name in the HTML does the pairing. You only need JavaScript to set names at click time with pageswap and pagereveal, or to skip the transition in some cases.

Does it work when going back?

Yes. traverse navigations are included. In our test, going back from the detail page to the list, the photo returned to its card with the same animation.

Does it slow down page loads?

The transition does not change what gets downloaded: no library, just a few lines of CSS. The new page paints under the transition overlay and is interactive while it animates. Chrome also documents blocking="render" to wait for an element, but advises against it unless you measure its impact.

Does it work on Shopify or Next.js?

On a Shopify theme every page is a same-origin document, so the rule applies the same way: it goes in the theme CSS and the name in the card and product templates (we tested with static pages, not on a store). In Next.js, navigation with Link happens inside the same document, so the cross-document rule does not apply there; that is the other half of the API.

Checklist

  • @view-transition { navigation: auto; } is in the CSS of both pages.
  • The opt-in sits inside @media (prefers-reduced-motion: no-preference).
  • The photo carries the same view-transition-name on the card and on the detail page.
  • Each name is unique on the page and does not start with a digit.
  • Images have width and height.
  • The group duration is between 200 and 400ms (illustrative; tune it to your site).
  • You tested with a click, forward and back, in Chrome and Safari.
  • In Firefox, navigation works the same without animation.

If your product page opens a window over the page, such as a size guide, also see how to build an accessible modal with dialog.

Saw this on Instagram? Comment TRANSICIONES on the Reel and I'll send you the guide.

Written by

Luis Morales

Luis Morales

Frontend and Shopify developer, EcomLabs

@luismoralesdev on Instagram

Published November 19, 2026

← Blog