View Transitions

`<ClientRouter />` turns your multi-page site into one that navigates without a full reload — and animates the transition.

4 min read Level 2/5 #astro#view-transitions#ClientRouter

What you'll learn

Add the client router to a layout
Animate transitions on specific elements
Persist islands across navigation

The browser’s View Transitions API lets you animate between two pages. Astro’s <ClientRouter /> wires it up — and intercepts clicks so navigation feels SPA-like without actually being an SPA.

Add It Once

Put <ClientRouter /> in your base layout:

---
import { ClientRouter } from "astro:transitions";
---
<html>
  <head>
    <ClientRouter />
    <title>...</title>
  </head>
  <body>
    <slot />
  </body>
</html>

That’s the whole baseline. Internal links now navigate without a full reload — and on supporting browsers, the page cross-fades.

Animating Specific Elements

Give an element a transition:name and Astro will morph between matching elements on the next page:

<!-- On /blog index -->
<img
  src={post.cover}
  alt=""
  transition:name={`hero-${post.id}`}
/>

<!-- On /blog/[slug] -->
<img
  src={post.cover}
  alt=""
  transition:name={`hero-${post.id}`}
/>

Click a card → the cover image animates into place on the detail page.

Persisting Islands

To keep an island mounted across navigation (a music player, an animation), use transition:persist:

<AudioPlayer client:load transition:persist />

The component keeps its state across page transitions.

Animation Customization

Astro provides a few built-in animations — fade, slide, none — via transition:animate:

<main transition:animate="slide">
  <slot />
</main>

For full control, write CSS keyframes targeting the view-transition pseudo-elements (::view-transition-old, ::view-transition-new).

Lifecycle Events

Hook into navigation if you need to:

document.addEventListener("astro:before-preparation", e => {
  // before the next page is fetched
});
document.addEventListener("astro:after-swap", e => {
  // DOM has been swapped to the new page
});

Browser Support

The View Transitions API ships in Chromium-based browsers and is landing in Firefox/Safari. Astro falls back to fast SPA-style navigation without the animation in browsers without support.

Up Next

Built-in internationalization.

i18n →