How to Add Page Transitions to Astro

By default, clicking a link loads a whole new page, with a flash of white in between. Transitions smooth that over, so your site feels more like an app. Astro gives you two ways to do it.

Option 1: One line of CSS, no JavaScript

Modern browsers can animate between pages on their own. Add this to a stylesheet that every page loads:

@view-transition {
  navigation: auto;
}

That’s it. Pages now cross-fade as you move between them. This is what we use on AstroBeginner, and it adds no JavaScript to the site.

Option 2: Astro’s ClientRouter

For more control, Astro’s ClientRouter component takes over navigation. Add it to your shared layout’s <head>:

---
import { ClientRouter } from 'astro:transitions';
---
<html lang="en">
  <head>
    <ClientRouter />
  </head>
  <body>
    <slot />
  </body>
</html>

Every page using this layout now transitions with a fade. The router also keeps things like a playing video alive between pages, if you ask it to.

Make an element travel between pages

The nicest effect is when one element appears to move from one page to the next, like a post title on a list growing into the heading on the post. Give the element the same transition:name on both pages:

<h1 transition:name="page-title">Welcome to my website</h1>

Each name can only be used once per page.

Change the animation

Use transition:animate to pick a different movement. The options are fade, which is the default, slide, none and initial:

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

Which should you use?

Start with the CSS version. It’s a single rule, and it’s enough for most sites. Move to ClientRouter when you need something it can do and CSS can’t, such as keeping an element on the page while the rest changes.

Frequently asked questions

Do page transitions slow my site down?

The CSS-only version adds nothing to your pages. Astro's ClientRouter adds a small script. Neither should make a noticeable difference on a well-built site.

Why don't I see any animation?

Check that the tag is in a layout that both pages share, and that your system isn't set to reduce motion. Browsers skip the animation when that setting is on.