View Transitions on Multi-Page Static Sites

The one thing single-page apps still do better than static sites is the moment between pages. Click a link on a multi-page site and the old page vanishes, there is a blank or half-painted frame, and the new page appears. Click in an app and the header stays put while the content slides. Teams have adopted whole client-side routers to get that effect, paying for it in JavaScript and INP.

Cross-document view transitions give multi-page sites the same polish with a few lines of CSS. Both pages opt in, and the browser snapshots the old page, loads the new one, and animates between them, keeping shared elements like the header visually continuous. This guide adds them to a static documentation site, handles reduced motion and layout stability, and measures the cost. It is part of Resource Hints and Navigation Speed.

Prerequisites

• A static multi-page site served over HTTPS with same-origin navigations.
• A shared layout, so the opt-in and element names can be added once.
• Ideally, speculation rules already in place, so the new page is ready instantly — see Instant Navigation with Speculation Rules.

Step 1: Opt In on Every Page

Add the at-rule to the global stylesheet. Both the outgoing and incoming page must include it; putting it in the site-wide CSS handles that.

/* global.css */
@view-transition {
  navigation: auto;
}

That alone produces a default cross-fade of about 250 ms between pages on same-origin navigations in supporting browsers. Browsers without support ignore it.

Step 2: Name the Persistent Elements

Elements with a view-transition-name are captured separately and animated from their old position and size to their new one. Give names to the elements that exist on both pages and should look continuous — the header, the sidebar, the page title.

.site-header { view-transition-name: site-header; }
.docs-sidebar { view-transition-name: docs-sidebar; }
main h1 { view-transition-name: page-title; }

/* keep the header perfectly still instead of cross-fading */
::view-transition-old(site-header),
::view-transition-new(site-header) { animation: none; mix-blend-mode: normal; }

/* slide the main content slightly */
::view-transition-old(root) { animation: 160ms ease-in both vt-fade-out; }
::view-transition-new(root) { animation: 200ms ease-out both vt-slide-in; }
@keyframes vt-fade-out { to { opacity: 0; } }
@keyframes vt-slide-in { from { opacity: 0; transform: translateY(8px); } }

Names must be unique on a page at the moment of the transition. A name used on two elements aborts the transition. On list pages where you want a card to morph into the article's hero, generate unique names per item from the slug (view-transition-name: card-{{ slug }}) and apply the same name to the hero on the article page.

Step 3: Respect Reduced Motion

Readers who have asked their operating system for reduced motion should get an instant swap, not a slide:

@media (prefers-reduced-motion: reduce) {
  @view-transition { navigation: none; }
}

Disabling the transition entirely is simpler and more predictable than trying to design a "gentler" animation, and it is what most readers with the setting enabled expect.

Step 4: Keep the Transition From Hurting Metrics

Three checks keep view transitions from costing anything measurable.

LCP. The browser only starts the transition once the new page has produced its first rendered frame, and LCP is measured on the new page as normal. The transition animation does not delay the LCP timestamp. It can, however, delay the moment content appears visually if the incoming animation starts at opacity: 0 and runs long; keep the incoming animation at or below 200 ms.

CLS. Elements moving as part of a view transition are not counted as layout shifts. But the transition can reveal shifts that happen after it ends — a web font swap or a late image resizing the title — more obviously, because the reader's eye is following the animated element. Fix those first; see Eliminating Layout Shift from Web Fonts.

Render-blocking. The new page must not be held back waiting for the transition. Avoid <link rel="expect"> render-blocking hints unless you know you need them, and never add a large stylesheet only for transition effects; the rules above add under 1 KB.

Measured Impact

The docs site measured before and after enabling transitions, with speculation rules already in place. Lab numbers from Lighthouse user flows (navigation from one guide to the next); field numbers from RUM over two weeks each, Chrome only.

Native Transitions or a Client Router?

Astro's <ClientRouter /> (formerly <ViewTransitions />) and similar routers intercept link clicks, fetch the next page with JavaScript and swap the DOM, animating with the same view transition API. That works in browsers without native cross-document support and allows persistent state such as a playing video across pages. It also ships a router of roughly 12–15 KB, changes navigation semantics (scripts must handle re-initialisation on astro:page-load), and turns every navigation into JavaScript work, which on the docs site raised INP p75 on navigation-heavy sessions by about 20 ms.

For content sites, native cross-document transitions are the better default: no JavaScript, no change in how scripts run, and graceful fallback to ordinary navigation. Reach for a client router only when you need state that survives navigation.

Debugging a Transition That Looks Wrong

When a transition flickers, jumps or does not run, three tools find the cause quickly. Chrome DevTools' Animations panel captures view transitions; slow them to 10% speed and step through to see which named element is misbehaving. The Elements panel shows the ::view-transition pseudo-element tree during a paused transition, which makes duplicate or missing names obvious. And the console logs an explicit error when a transition is skipped because two elements share a name, which is the most common reason one silently fails to run on list pages. A final check is to test with the CPU throttled four times in DevTools: an animation that looks smooth on a laptop can stutter on a phone if it animates properties such as width or top instead of transform and opacity.

Pitfalls & Rollback

• Duplicate names. Two elements with the same view-transition-name on one page abort the transition. Generate names from unique slugs on list pages.
• Long animations. Anything over about 300 ms makes navigation feel slower, not smoother. Keep incoming animations near 200 ms.
• Ignoring reduced motion. Always disable transitions under prefers-reduced-motion: reduce.
• Naming large, changing elements. Naming the whole <main> makes the browser morph between two very different sizes, which looks like a glitch. Name stable elements; let the root cross-fade.
• Transitions on external or download links. Cross-document transitions only run on same-origin navigations; do not design flows that assume an animation when leaving the site or opening a file.
• Rollback: delete the @view-transition rule. Navigation reverts to the default immediately, with no other effect.

Conclusion

Cross-document view transitions give a multi-page static site the one thing it lacked compared with an app: continuity between pages. The whole feature is under 1 KB of CSS — an opt-in rule, a few element names, a reduced-motion override — with no JavaScript and no measurable effect on LCP, INP or CLS on the docs site tested. Combined with speculation rules, navigations become instant and visually continuous, which is most of what readers mean when they say a site "feels fast".

FAQ

Do cross-document view transitions need JavaScript?

No. Both pages opt in with the @view-transition CSS at-rule, and the browser handles snapshotting and animating. JavaScript is only needed for advanced cases such as choosing a different animation per navigation type.

Do view transitions affect Core Web Vitals?

They do not delay LCP, because the transition begins after the new page has rendered its first frame. Elements animated by the transition do not count as layout shifts. Long or complex animations can make the page feel slower, so keep them short.

What happens in browsers without support?

They ignore the at-rule and navigate normally, with no animation. The feature is a progressive enhancement and never breaks navigation.

Should I use Astro's ClientRouter or native cross-document transitions?

Prefer native cross-document transitions for static content sites. They need no client-side router or JavaScript. Astro's ClientRouter adds a router so transitions also work in browsers without native support, at the cost of shipping and running that router.

Related

• Parent: Resource Hints and Navigation Speed — navigation speed techniques together.
• Instant Navigation with Speculation Rules — making the incoming page ready before the click.
• Prefetching Links in Astro — and how ClientRouter changes prefetch defaults.
• Fixing CLS from Sticky Headers and Anchor Links — stabilising the header you name.
• Astro Islands vs Full Hydration Performance — why avoiding a router keeps INP low.