View Transitions
Guidelines for implementing page transitions using Astro's View Transitions.
astro
## Astro View Transitions Guidelines
1. Purpose: Enables smooth, animated transitions between pages without a full browser refresh, mimicking Single-Page Application (SPA) behavior within Astro's Multi-Page App (MPA) architecture. Uses the browser's native View Transitions API where available, with configurable fallbacks.
2. Enablement: Add the `<ClientRouter />` component from `astro:transitions` to the `<head>` of your page or layout.
```astro
---
import { ClientRouter } from 'astro:transitions';
---
<head>
<title>My Page</title>
<ClientRouter />
</head>
<body>
<!-- Page content -->
</body>
```
- Adding it to a shared layout enables site-wide view transitions.
- Adding it to a single page enables transitions _away_ from that page.
3. Automatic Prefetching: Adding `<ClientRouter />` automatically enables prefetching with the `prefetch: { prefetchAll: true }` default. Links will be prefetched on hover/focus to speed up transitions. This can be configured/disabled via the `prefetch` setting in `astro.config.mjs`.
4. Transition Directives: Control how elements participate in transitions. Apply these directives to HTML elements.
- `transition:name="unique-name"`: Assigns a unique name to an element. If an element with the same name exists on the next page, Astro attempts to animate the transition between them (e.g., morphing).
- `transition:persist="unique-id" | ComponentName`: Keeps an element or component island persistent across navigation. The element/island must exist on both the source and destination pages with the same `transition:persist` value. Useful for maintaining state in islands (e.g., video players, maps).
- `transition:animate="animation-name"`: Specifies a built-in or custom animation for an element during the transition.
- Built-ins: `fade` (default), `slide`, `none`.
- Custom: Define animations using CSS (see docs).
5. Router Control (`astro:transitions/client` module):
- Preventing Client-side Navigation: Add the `data-astro-reload` attribute to an `<a>` tag to force a full page refresh for that link, bypassing the view transition.
- Triggering Navigation Programmatically: Use `navigate(href, options?)` from `astro:transitions/client` in client-side scripts.
```javascript
import { navigate } from "astro:transitions/client";
document.getElementById("my-button").onclick = () => {
navigate("/next-page");
};
```
- Replacing History: Use `navigate('/next-page', { history: 'replace' })` to replace the current history entry instead of pushing a new one.
- Forms: View transitions work automatically with standard HTML `<form>` submissions (GET and POST).
6. Fallback Control: Configure behavior for browsers that don't support the native View Transitions API in `astro.config.mjs`.
```javascript
// astro.config.mjs
import { defineConfig } from "astro/config";
export default defineConfig({
viewTransitions: {
fallback: "animate", // 'animate' (default, uses Astro's fallback animations) or 'swap' (no animation, just content swap)
},
});
```
7. Script Behavior:
- Standard `<script>` tags (not `type="module"`) in the `<head>` are executed once on initial load and not re-executed on navigation.
- `<script>` tags in the `<body>` and all `<script type="module">` tags are re-executed after every navigation by default.
- Add the `data-astro-rerun` attribute to a `<script>` tag to force re-execution even if it normally wouldn't, or to prevent re-execution if it normally would.
- Scripts marked `is:inline` behave like standard scripts (run once in `<head>`, rerun in `<body>`).
8. Lifecycle Events: Hook into the navigation process using events dispatched on `document`.
- `astro:before-preparation`: Before loading starts. Can alter loading or direction.
- `astro:after-preparation`: After new page content is loaded/parsed, before transition starts.
- `astro:before-swap`: Just before the new DOM replaces the old one (inside the transition). Can modify `event.newDocument` or provide a custom `event.swap()` implementation.
- `astro:after-swap`: Immediately after the DOM swap. Useful for restoring state.
- `astro:page-load`: Fires after navigation is complete and the page is interactive. Runs on initial load and subsequent navigations.
9. Accessibility:
- Route Announcement: `<ClientRouter />` automatically announces the new page title (or `<h1>`, or path) to assistive technologies after navigation.
- Reduced Motion: Respects `prefers-reduced-motion` setting, disabling animations automatically.
Reference: [Astro View Transitions Docs](mdc:https:/docs.astro.build/en/guides/view-transitions)