How to Add Page Transitions in Astro: Simple Guide

To add page transitions in Astro, use client-side JavaScript to detect navigation events and apply CSS animations during page changes. You can wrap your page content in a component that triggers animations on mount and unmount, creating smooth transitions between pages.

Syntax

Page transitions in Astro involve three main parts:

• Client-side script: Detects when navigation happens.
• Animation CSS: Defines how the page enters and leaves.
• Wrapper component: Applies animations on page load and unload.

This pattern uses Astro's client:load or client:idle directives to run JavaScript only in the browser.

jsx

import { onMount } from 'solid-js';

export default function PageTransition() {
  onMount(() => {
    const container = document.querySelector('#page-container');
    container.classList.add('fade-in');

    return () => {
      container.classList.remove('fade-in');
      container.classList.add('fade-out');
    };
  });

  return <div id="page-container"><slot /></div>;
}

Example

This example shows a simple fade transition between pages using Astro with SolidJS for client-side control and CSS animations.

astro

---
import PageTransition from '../components/PageTransition.jsx';
---

<PageTransition client:load>
  <main>
    <h1>Welcome to Astro with Page Transitions</h1>
    <p>Navigate between pages to see the fade effect.</p>
  </main>
</PageTransition>

<style>
  #page-container {
    opacity: 0;
    transition: opacity 0.5s ease-in-out;
  }
  #page-container.fade-in {
    opacity: 1;
  }
  #page-container.fade-out {
    opacity: 0;
  }
</style>

Output

Page content fades in on load and fades out on navigation, creating a smooth transition effect.

Common Pitfalls

• Not using client directives like client:load causes animations to run on the server, which won't work.
• Forgetting to wrap page content in a transition component means no animation triggers.
• Not handling unmount animations can cause abrupt page changes without fade-out effects.

astro

/* Wrong: No client directive, animation won't run in browser */
<PageTransition>
  <main>Content</main>
</PageTransition>

/* Right: Use client:load to run animation in browser */
<PageTransition client:load>
  <main>Content</main>
</PageTransition>

Quick Reference

• Use client:load or client:idle to run JS in browser.
• Wrap page content in a component that adds/removes CSS classes for animation.
• Define CSS transitions for smooth fade or slide effects.
• Test navigation to ensure animations trigger on both entering and leaving pages.

Key Takeaways

Use client directives like client:load to run page transition scripts in the browser.

Wrap your page content in a component that controls CSS animation classes on mount and unmount.

Define clear CSS animations for fade or slide effects to create smooth transitions.

Always test transitions on navigation to ensure both entering and leaving animations work.

Avoid running animation code on the server by using Astro's client directives.