W3cubDocs

/Astro

View Transitions (Experimental)

Support for opt-in, per-page, view transitions in Astro projects can be enabled behind an experimental flag. View transitions update your page content without the browser’s normal, full-page navigation refresh and provide seamless animations between pages.

Astro provides a <ViewTransitions /> routing component that can be added to a single page’s <head> to control page transitions as you navigate away to another page, an effect traditionally only possible with client-side routing. Add this component to a reusable .astro component, such as a common head or layout, for animated page transitions across your entire site (SPA mode).

Astro’s view transitions support is powered by the new View Transitions browser API and also includes:

A few built-in animations, such as slide and fade.
Support for both forwards and backwards navigation animations.
The ability to fully customize all aspects of transition animation, and build your own animations.
Control over fallback behavior for browsers that do not yet support the View Transition APIs.

Enabling View Transitions in your Project

You can enable support for animated page transitions through the experimental viewTransitions flag in your Astro config:

astro.config.mjs

Full site view transitions (SPA mode)

Import and add the <ViewTransitions /> component to your common <head> or shared layout component. Astro will create default page animations based on the similiarities between the old and new page, and will also provide fallback behavior for unsupported browsers.

The example below shows adding view transitions site-wide by importing and adding this component to a <CommonHead /> Astro component:

components/CommonHead.astro

You can also add view transitions on a per-page basis. Import the <ViewTransitions /> component and place it directly inside of a page’s <head>.

Transition Directives

Use optional transition:* directives on page elements in your .astro components for finer control over the page transition animation during navigation.

transition:name: Allows you to override Astro’s default element matching for old/new content animation and specify a transition name to associate a pair of DOM elements.
transition:animate: Allows you to override Astro’s default animation by specifying an animation type. Use Astro’s built-in animation directives or create custom transition animations.

Naming a transition

Astro will automatically assign elements found in both the old page and the new page a shared, unique view-transition-name. This pair of matching elements is inferred by both the type of element and its location in the DOM.

In some cases, you may want or need to identify these elements yourself. You can specify a name for a pair of elements using the transition:name directive.

Note that the transition:name must be distinct per element. Set this manually when Astro can’t infer a proper name itself, or for more fine control over matching elements.

Built-in Animation Directives

Astro comes with a few built-in animations to override the default morph transition. Add the transition:animate directive to try Astro’s slide or fade transitions.

morph (default): The browser determines the best way to animate the element depending on how similar the pages are. For example, if the element is positionally different between pages, it will appear to float to its new position. If the element is in the exact same position, it will appear to not move at all.
slide: An animation where the old content slides out to the left and new content slides in from the right. On backwards navigation, the animations are the opposite.
fade: A cross-fade where the old content fades out and the new content fades in.

The example below produces a slide animation for the body content while keeping a positionally-identical header in place:

Customizing Animations

You can customize all aspects of a transition with any CSS animation properties.

To customize a built-in animation, first import the animation from astro:transitions, and then pass in customization options.

The example below customizes the duration of the built-in fade animation:

You can also define your own animations for use with transition:animate by defining both the forwards and backwards behavior, as well as new and old pages, according to the following types:

The following example shows all the necessary properties to define a custom fade animation:

Fallback control

The <ViewTransitions /> router works best in browsers that support View Transitions (i.e. Chromium browsers), but also includes default fallback support for other browsers. Even if the browser does not support the View Transitions API, Astro will still provide in-browser navigation using one of the fallback options for a comparable experience.

You can override Astro’s default fallback support by adding a fallback property on the <ViewTransitions /> component and setting it to swap or none:

animate (default, recommended) - Astro will simulate view transitions using custom attributes before updating page content.
swap - Astro will not attempt to animate the page. Instead, the old page will be immediately replaced by the new one.
none - Astro will not do any animated page transitions at all. Instead, you will get full page navigation in non-supporting browsers.

When navigating between pages with the <ViewTransitions /> component, scripts are run in sequential order to match browser behavior.

If you have code that sets up global state, this state will need to take into account that the script might execute more than once. Check for the global state in your <script> tag, and conditionally execute your code where possible:

Module scripts are only ever executed once because the browser keeps track of which modules are already loaded. For these scripts, you do not need to worry about re-execution.

`astro:load`

An event that fires at the end of page navigation, after the new page is visible to the user and blocking styles and scripts are loaded. You can listen to this event on the document.

The <ViewTransitions /> component fires this event both on initial page navigation (MPA) and any subsequent navigation, either forwards or backwards.

You can use this event to run code on every page navigation, or only once ever:

`astro:beforeload`

An event that fires immediately after the new page replaces the old page. You can listen to this event on the document.

This event is useful to restore any state on the DOM that needs to transfer over to the new page.

For example, if you are implementing dark mode support, this event can be used to restore state across page loads:

`prefers-reduced-motion`

Astro’s <ViewTransitions /> component includes a CSS media query that disables all view transition animations, including fallback animation, whenever the prefer-reduced-motion setting is detected. Instead, the browser will simply swap the DOM elements without an animation.