Introduction
Single-page apps (SPAs) feel smooth because navigation doesn’t reload the page — but you pay for it with megabytes of client-side routing, state management, and hydration. Astro’s View Transitions give you that smooth feel on a multi-page site with zero extra JavaScript.
This site uses them. Here’s how to add them to yours.
What are View Transitions?
The browser’s native View Transitions API animates between two DOM states. Astro wraps it so that navigating between pages feels like an in-app transition — fade, slide, or morph — instead of a full reload.
The best part: Astro only sends the changed HTML (not the whole page), and morphs the DOM. The result is SPA-like speed on a static site.
Setup (one line)
Add to your layout’s <head>:
---
import { ViewTransitions } from 'astro:transitions';
---
<head>
<ViewTransitions />
</head>
That’s it. Every link now transitions smoothly. Astro handles prefetching, scroll restoration, and focus management.
Default transition: fade
Out of the box, Astro fades between pages. For most sites, that’s enough.
Custom transitions
Slide
---
import { ViewTransitions } from 'astro:transitions';
---
<ViewTransitions />
Then in CSS:
::view-transition-old(root) {
animation: slide-out 0.3s ease;
}
::view-transition-new(root) {
animation: slide-in 0.3s ease;
}
@keyframes slide-out { to { transform: translateX(-100%); } }
@keyframes slide-in { from { transform: translateX(100%); } }
Morph a specific element
Give an element a transition:name and it morphs between pages:
<!-- Page A -->
<img src="/avatar.png" transition:name="avatar" />
<!-- Page B -->
<img src="/avatar.png" transition:name="avatar" />
The image smoothly animates from its position on page A to its position on page B. Great for shared headers, avatars, and hero images.
Persist an element across navigations
<audio src="/bg.mp3" transition:persist />
transition:persist keeps the element (and its state) alive across page loads — perfect for audio players, video, or interactive widgets.
Prefetching
Astro prefetches linked pages on hover/focus by default with View Transitions enabled. You can tune it:
---
import { ViewTransitions } from 'astro:transitions';
---
<ViewTransitions prefetch={{ defaultStrategy: 'viewport' }} />
Strategies: hover (default), viewport (prefetch when link enters viewport), load (prefetch all on page load).
Handling lifecycle events
View transitions add new lifecycle events:
document.addEventListener('astro:before-preparation', () => {
// before the new page is fetched
});
document.addEventListener('astro:after-swap', () => {
// after the DOM is swapped, before paint
// re-init any non-Astro scripts here
});
document.addEventListener('astro:page-load', () => {
// after the new page is fully loaded
});
Use astro:page-load instead of DOMContentLoaded for any script that needs to run on every navigation.
Common mistakes
- Forgetting
astro:page-load— scripts usingDOMContentLoadedonly fire once. Useastro:page-loadfor per-navigation init. - Persisting too much —
transition:persiston many elements defeats the purpose (it keeps old DOM around). Use sparingly. - Ignoring reduced motion — wrap transitions in
@media (prefers-reduced-motion: no-preference)for accessibility. - Breaking analytics — page views need re-firing on
astro:page-load(GA’sgtag('config', ...)withpage_path). - Not testing on Safari — View Transitions shipped in Safari 18+. Older browsers fall back to normal navigation (graceful degradation).
Key Concepts
- View Transitions = native browser API for animating between page states
<ViewTransitions />= Astro’s wrapper (one line)transition:name= morph a specific element across pagestransition:persist= keep element/state across navigationsastro:page-load= per-navigation lifecycle event
What to Try Next
- Add
transition:nameto your site’s logo and avatar for a smooth morph. - Persist a music player across page navigations.
- Combine with Astro islands — islands hydrate normally after transition.
- Measure the LCP improvement in Lighthouse (transitions often improve perceived performance).
FAQ
Do View Transitions work with React/Vue/Svelte islands?
Yes — islands hydrate normally after the transition. The transition only affects the static HTML shell.
Is this supported in all browsers?
Chrome/Edge 111+, Safari 18+, Firefox 126+. Older browsers fall back to instant navigation (no animation, no breakage). Progressive enhancement.
Does this break my analytics?
Page views need re-firing. With GA, call gtag('config', GA_ID, { page_path: window.location.pathname }) inside an astro:page-load listener. Most analytics scripts handle this if loaded with is:inline + the listener.