> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/withastro/astro/llms.txt
> Use this file to discover all available pages before exploring further.
# View Transitions
> Create smooth page transitions with Astro's View Transitions API for SPA-like navigation
View Transitions provide smooth, animated transitions between pages in your Astro site, creating a single-page application (SPA) experience while maintaining the benefits of multi-page architecture.
## Getting Started
Enable view transitions by adding the `` component to your layout's ``:
```astro src/layouts/Layout.astro theme={null}
---
import { ViewTransitions } from 'astro:transitions';
---
My Site
```
With just this one component, Astro handles all the complexity of page transitions, including routing, animation, and state management.
## How It Works
When a user clicks a link:
Astro intercepts the navigation and prevents the default page load
The new page is fetched in the background
Elements fade out, move, or morph based on their transition names
The DOM is updated with the new page content
Elements animate in and the transition completes
## Basic Transitions
By default, all pages get a cross-fade transition. Customize transitions using the `transition:*` directives:
```astro src/pages/index.astro theme={null}
---
import { fade, slide } from 'astro:transitions';
---
Welcome
```
## Transition Directives
### transition:name
Persist or morph elements across pages by giving them the same name:
```astro src/pages/products/[id].astro theme={null}
---
const { id } = Astro.params;
const product = await getProduct(id);
---
{product.name}
```
Elements with the same `transition:name` will smoothly morph between pages:
```astro src/pages/products/index.astro theme={null}
---
const products = await getProducts();
---
```
When navigating from the grid to a product page, the image and title smoothly animate from their list position to their detail position.
### transition:persist
Keep elements in the DOM across page transitions:
```astro theme={null}
```
Persisted elements maintain their state (video position, form inputs, etc.).
### transition:animate
Customize animation styles:
```astro theme={null}
---
import { fade, slide } from 'astro:transitions';
---
```
## Directional Animations
Create different animations for forward and backward navigation:
```astro theme={null}
---
import { slide } from 'astro:transitions';
---
Content
```
The `slide` animation automatically:
* Slides **left** when going forward
* Slides **right** when going back
## Lifecycle Events
Listen to transition events to run code during transitions:
```astro theme={null}
```
### Event Reference
Fires before fetching the new page
Fires after fetching and parsing the new page
Fires before updating the DOM
Fires after updating the DOM
Fires when the page is fully loaded and interactive
## Preventing Transitions
Disable transitions for specific links:
```astro theme={null}
Transitions enabledNo transitionExternal link
```
## Fallback Behavior
View Transitions gracefully degrade in browsers that don't support the View Transitions API:
* Modern browsers: Smooth animated transitions
* Older browsers: Standard page navigation
* JavaScript disabled: Normal links work as expected
The View Transitions API is supported in Chrome, Edge, and other Chromium browsers. Safari and Firefox users get standard navigation.
## Preserving State
### Form Inputs
Persist form state across navigation:
```astro theme={null}
```
### Media Playback
Keep videos and audio playing:
```astro theme={null}
```
### Third-Party Scripts
Persist widgets that shouldn't reinitialize:
```astro theme={null}
```
## Advanced Patterns
### Loading Indicators
Show loading state during transitions:
```astro src/components/LoadingBar.astro theme={null}
```
### Scroll Restoration
Customize scroll behavior:
```astro theme={null}
```
### Page-Specific Transitions
Different animations for different pages:
```astro src/pages/index.astro theme={null}
---
import { fade } from 'astro:transitions';
---
```
## View Transition Scope
Create isolated transition contexts:
```astro theme={null}
---
import { createAnimationScope } from 'astro:transitions';
const scope = createAnimationScope('my-section');
---
```
## Performance Tips
Only add `transition:name` to elements that truly need morphing. Too many can impact performance.
Transitions under 300ms feel snappy. Avoid durations over 500ms.
Use optimized images for smoother transitions, especially for morphing elements.
View transitions wait for the new page to load. Test on throttled connections.
## Accessibility
View Transitions respect user preferences:
```css theme={null}
/* Respect prefers-reduced-motion */
@media (prefers-reduced-motion: reduce) {
:root {
--animation-duration: 0.01ms !important;
}
}
```
Astro automatically:
* Announces page changes to screen readers
* Updates the document title
* Manages focus appropriately
* Respects `prefers-reduced-motion`
## Troubleshooting
* Ensure `` is in your layout's ``
* Check that you're using the same layout across pages
* Verify the View Transitions API is supported in your browser
* Use `transition:persist` for elements that should maintain state
* Ensure CSS is loaded before the transition starts
* Check for conflicting animations
* Use the `astro:page-load` event instead of `DOMContentLoaded`
* Wrap script logic in event listeners that re-run on navigation
## Related Resources
Client-side interactivity
Page routing and navigation
Shared page layouts
Optimization techniques
