How to Add Page Transitions to Astro

Click a link on most sites. The whole page reloads. You see a flash of white in between. A page transition smooths that over. Your site then feels more like an app. Astro gives you two ways to do it.

Option 1: One line of CSS, no JavaScript

CSS is the code that styles your pages. Modern browsers can fade between pages on their own. You just have to ask. Add this to a stylesheet that every page loads:

@view-transition {
  navigation: auto;
}

That is it. Pages now cross-fade as you move between them. We use this on Astro Nursery. It adds no JavaScript to the site. JavaScript is the code that makes pages do things.

Option 2: Astro’s ClientRouter

Want more control? Astro’s ClientRouter component takes over page moves. A component is a reusable piece of a page. Add it to the <head> of your shared layout. A layout is the frame that all your pages share.

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

Every page that uses this layout now fades between pages. The router can do more. It can keep a playing video alive from one page to the next, if you ask it to.

Make an element travel between pages

This is the nicest effect. One item seems to move from one page to the next. Think of a post title in a list. It grows into the big heading on the post page. To do it, give the item the same transition:name on both pages:

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

Use each name only once per page.

Change the animation

Use transition:animate to pick a different movement. You have four choices. fade is the default. The others are slide, none and initial:

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

Which should you use?

Start with the CSS version. It is one rule. It is enough for most sites. Move to ClientRouter when you need more. For example, it can keep one item on the page while the rest changes. CSS cannot do that.

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. On a well-built site, you should not notice either one.

Why don't I see any animation?

Check two things. First, the tag must be in a layout that both pages share. Second, your system must not be set to reduce motion. Browsers skip the animation when that setting is on.