Skip to content
AITroveRead. Build. Understand.
Reading list
Make this comfortable

CSS @view-transition: opt in only the pages that can tolerate a cross-page animation

Last updated: 1 Oct 20265 min read
tutorial
BeginnerBy AITrove Editorial

The @view-transition rule can opt a document into cross-document view transitions with navigation: auto. Both the departing and arriving documents must opt in, and the navigation must satisfy the browser's same-origin and navigation rules. A normal link and a fully rendered destination remain necessary; CSS does not replace navigation or provide a router.

When to use it

An incident index and case detail page share a site shell. Their common stylesheet opts both pages in, then keeps the transition short. The ordinary link works when the feature is unavailable, when one page does not opt in, or when a navigation does not qualify. Test a direct page load, a same-origin link, back navigation, a redirect, and an external link. Do not promise the same animation across a cross-origin redirect. The default transition may capture the whole root; review whether sensitive on-screen information can remain visible in a snapshot during navigation. If a named element is added later, ensure each captured document has one matching identity. Keep headings and focus behavior correct after navigation. A reduced-motion preference removes the authored root animation, while the destination content and link behavior remain unchanged. The page should never delay rendering to wait for a decorative transition.

css
@view-transition { navigation: auto; }
::view-transition-old(root), ::view-transition-new(root) { animation-duration: 140ms; }
@media (prefers-reduced-motion: reduce) { ::view-transition-old(root), ::view-transition-new(root) { animation: none; } }

Cost and verification

A full-page snapshot can consume more memory and paint time than a narrow named element. Profile navigation on a realistic page before keeping the effect. Cross-document support is still limited, so a site must behave cleanly when the at-rule is ignored. Both documents need the opt-in; a shared stylesheet makes that easier but can also opt in an unsuitable page by accident. Check the route set rather than applying it globally without review. The transition does not transfer application state, stop a network request, or manage focus in an application shell. Keep those contracts independent of the animation.

Common Mistakes

  • Do not assume an opt-in on one page is sufficient.
  • Do not expect cross-origin navigation to use this transition.
  • Do not let a page-wide snapshot delay or obscure the destination content.

Connected lessons

css
reference
web
Storage details