View Transitions
This content is not available in your language yet.
Astro supports opt-in, per-page, view transitions with just a few lines of code. 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. It provides a lightweight client-side router that intercepts navigation and allows you to customize the transition between pages.
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 animation options, such as
fade
,slide
, andnone
. - Support for both forwards and backwards navigation animations.
- The ability to fully customize all aspects of transition animation, and build your own animations.
- The option to prevent client-side navigation for non-page links.
- Control over fallback behavior for browsers that do not yet support the View Transition APIs.
- Automatic support for
prefers-reduced-motion
.
By default, every page will use regular, full-page, browser navigation. You must opt in to view transitions and can use them either on a per-page basis or site-wide.
Adding View Transitions to a Page
Section titled Adding View Transitions to a PageOpt in to using view transitions on individual pages by importing and adding the <ViewTransitions />
routing component to <head>
on every desired page.
Full site view transitions (SPA mode)
Section titled 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 similarities between the old and new page, and will also provide fallback behavior for unsupported browsers.
The example below shows adding Astro’s default page navigation animations site-wide, including the default fallback control option for non-supporting browsers, by importing and adding this component to a <CommonHead />
Astro component:
No other configuration is necessary to enable Astro’s default client-side navigation!
Use transition directives or override default client-side navigation on individual elements for finer control.
Transition Directives
Section titled Transition DirectivesAstro will automatically assign corresponding 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.
Use optional transition:*
directives on page elements in your .astro
components for finer control over the page transition behaviour 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 while replacing the old element with the new one by specifying an animation type. Use Astro’s built-in animation directives or create custom transition animations.transition:persist
: Allows you to override Astro’s default replacing old elements for new ones and instead persist components and HTML elements when navigating to another page.
Naming a transition
Section titled Naming a transitionIn some cases, you may want or need to identify the corresponding view transition elements yourself. You can specify a name for a pair of elements using the transition:name
directive.
Note that the provided transition:name
value can only be used once on each page. Set this manually when Astro can’t infer a proper name itself, or for more fine control over matching elements.
Maintaining State
Section titled Maintaining State
Dodane w:
astro@2.10.0
You can persist components and HTML elements (instead of replacing them) across page navigations using the transition:persist
directive.
For example, the following <video>
will continue to play as you navigate to another page that contains the same video element. This works for both forwards and backwards navigation.
You can also place the directive on an Astro island (a UI framework component with a client:
directive). If that component exists on the next page, the island from the old page with its current state will continue to be displayed, instead of replacing it with the island from the new page.
In the example below, the count
will not be reset when navigating back and forth across pages that contain the <Counter />
component with the transition:persist
attribute.
You can also manually identify corresponding elements if the island/element is in a different component between the two pages.
As a convenient shorthand, transition:persist
can alternatively take a transition name as a value.
When you add transition:persist
to an island, the state is retained upon navigation, but any props that change will be carried over to the new page, causing your component to re-render with new props, but the existing state.
Built-in Animation Directives
Section titled Built-in Animation DirectivesAstro comes with a few built-in animations to override the default fade
transition. Add the transition:animate
directive to individual elements to customize the behavior of specific transitions.
fade
(default): An opinionated crossfade animation. The old content fades out and the new content fades in.initial
: Opt out of Astro’s opinionated crossfade animation and use the browser’s default styling.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.none
: Disable the browser’s default animations. Use on a page’s<html>
element to disable the default fade for every element on the page.
Combine directives for full control over your page animation. Set a page default on the <html>
element, and override on any individual elements as desired.
The example below produces a slide animation for the body content while disabling the browser’s default fade animation for the rest of the page:
Customizing Animations
Section titled Customizing AnimationsYou 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:
Router control
Section titled Router controlThe <ViewTransitions />
router handles navigation by listening to:
- Clicks on
<a>
elements. - Backwards and forwards navigation events.
The following options allow you to further control when navigation occurs within the router:
data-astro-reload
: an<a>
tag attribute to force a full-page navigationdata-astro-history="auto | push | replace"
: an<a>
tag attribute to control the browser’s historynavigate(href, options)
: a method available to any client script or client component to trigger navigation
Preventing client-side navigation
Section titled Preventing client-side navigationThere are some cases where you cannot navigate via client-side routing since both pages involved must use the <ViewTransitions />
router to prevent a full-page reload. You may also not want client-side routing on every navigation change and would prefer a traditional page navigation on select routes instead.
You can opt out of client-side routing on a per-link basis by adding the data-astro-reload
attribute to any <a>
or <form>
tag. This attribute will override any existing <ViewTransitions />
component and instead trigger a browser refresh during navigation.
The following example shows preventing client-side routing when navigating to an article from the home page only. This still allows you to have animation on shared elements, such as a hero image, when navigating to the same page from an article listing page:
Links with the data-astro-reload
attribute will be ignored by the router and a full-page navigation will occur.
Trigger navigation
Section titled Trigger navigationYou can also trigger client-side navigation via events not normally listened to by the <ViewTransitions />
router using navigate
. This function from the astro:transitions/client
module can be used in scripts, and in framework components that are hydrated with a client directive.
The following example shows an Astro component that navigates a visitor to another page they select from a menu:
The following example implements the same using navigate()
in a React <Form />
component:
The <Form />
component can then be rendered on an Astro page that uses the <ViewTransitions />
router, with a client directive:
The navigate
method takes these arguments:
href
(required) - The new page to navigate to.options
- An optional object with the following properties:history
:'push'
|'replace'
|'auto'
'push'
: the router will usehistory.pushState
to create a new entry in the browser history.'replace'
: the router will usehistory.replaceState
to update the URL without adding a new entry into navigation.'auto'
(default): the router will attempthistory.pushState
, but if the URL is not one that can be transitioned to, the current URL will remain with no changes to the browser history.
formData
: A FormData object forPOST
requests.
For backward and forward navigation through the browser history, you can combine navigate()
with the built-in history.back()
, history.forward()
and history.go()
functions of the browser. If navigate()
is called during the server-side render of your component, it has no effect.
Replace entries in the browser history
Section titled Replace entries in the browser historyNormally, each time you navigate, a new entry is written to the browser’s history. This allows navigation between pages using the browser’s back
and forward
buttons.
The <ViewTransitions />
router allows you to overwrite history entries by adding the data-astro-history
attribute to any individual <a>
tag.
The data-astro-history
attribute can be set to the same three values as the history
option of the navigate()
function:
data-astro-history
: 'push'
| 'replace'
| 'auto'
'push'
: the router will usehistory.pushState
to create a new entry in the browser history.'replace'
: the router will usehistory.replaceState
to update the URL without adding a new entry into navigation.'auto'
(default): the router will attempthistory.pushState
, but if the URL is not one that can be transitioned to, the current URL will remain with no changes to the browser history.
The following example navigates to the /main
page but does not add a new entry to the browsing history. Instead, it reuses the current entry in the history (/confirmation
) and overwrites it.
This has the effect that if you go back from the /main
page, the browser will not display the /confirmation
page, but the page before it.
Transitions with forms
Section titled Transitions with forms
Dodane w:
astro@4.0.0
The <ViewTransitions />
router will trigger in-page transitions from <form>
elements, supporting both GET
and POST
requests.
By default, Astro submits your form data as multipart/form-data
when your method
is set to POST
. If you want to match the default behavior of web browsers, use the enctype
attribute to submit your data encoded as application/x-www-form-urlencoded
:
You can opt out of router transitions on any individual form using the data-astro-reload
attribute:
Fallback control
Section titled Fallback controlThe <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.
The initial
browser animation is not simulated by Astro. So any element using this animation will not currently be animated.
Client-side navigation process
Section titled Client-side navigation processWhen using the <ViewTransitions />
router, the following steps occur to produce Astro’s client-side navigation:
-
A visitor to your site triggers navigation by any of the following actions:
- Clicking an
<a>
tag linking internally to another page on your site. - Clicking the back button.
- Clicking the forward button.
- Clicking an
-
The router starts fetching the next page.
-
The router adds the
data-astro-transition
attribute to the HTML element with a value of'forward'
or'back'
as appropriate. -
The router calls
document.startViewTransition
. This triggers the browser’s own view transition process. Importantly, the browser screenshots the current state of the page. -
Inside the
startViewTransition
callback, the router performs a swap, which consists of the following sequence of events:-
The contents of the
<head>
are swapped out, with some elements kept:- Stylesheet DOM nodes are left in if they exist on the new page, to prevent FOUC.
- Scripts are left in if they exist on the new page.
- Any other head elements with
transition:persist
are left in if there is a corresponding element in the new page.
-
The
<body>
is completely replaced with the new page’s body. -
Elements marked
transition:persist
are moved over to the new DOM if they exist on the new page. -
Scroll position is restored if necessary.
-
The
astro:after-swap
event is triggered on thedocument
. This is the end of the swap process.
-
-
The router waits for any new stylesheets to load before resolving the transition.
-
The router executes any new scripts added to the page.
-
The
astro:page-load
event fires. This is the end of the navigation process.
Script behavior during page navigation
Section titled Script behavior during page navigationWhen 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, including those that add event listeners for DOMContentLoaded
, are only ever executed once because the browser keeps track of which modules are already loaded. You must add listeners for a Lifecycle event to re-execute scripts during client-side page navigation.
See the Add View Transitions Tutorial for an example of updating existing scripts in a project.
Lifecycle events
Section titled Lifecycle eventsThe <ViewTransition />
router fires a number events on the document
during navigation. These events provide hooks into the lifecycle of navigation, allowing you to do things like show indicators that a new page is loading, override default behavior, and restore state as navigation is completing.
The navigation process involves a preparation phase, when new content is loaded; a DOM swap phase, where the old page’s content is replaced by the new page’s content; and a completion phase where scripts are executed, loading is reported as completed and clean-up work is carried out.
Astro’s View Transition API lifecycle events in order are:
before-
events allow you to influence and modify actions that are about to take place, and after-
events are notifications that a phase is complete.
While some actions can be triggered during any event, some tasks can only be performed during a specific event for best results, such as displaying a loading spinner before preparation or overriding animation pairs before swapping content.
astro:before-preparation
Section titled astro:before-preparation
Dodane w:
astro@3.6.0
An event that fires at the beginning of the preparation phase, after navigation has started (e.g. after the user has clicked a link), but before content is loaded.
This event is used:
- To do something before loading has started, such as showing a loading spinner.
- To alter loading, such as loading content you’ve defined in a template rather than from the external URL.
- To change the
direction
of the navigation (which is usually eitherforward
orbackward
) for custom animation.
Here is an example of using the astro:before-preparation
event to load a spinner before the content is loaded and stop it immediately after loading. Note that using the loader callback in this way allows asynchronous execution of code.
astro:after-preparation
Section titled astro:after-preparation
Dodane w:
astro@3.6.0
An event that fires at the end of the preparation phase, after the new page’s content has been loaded and parsed into a document. This event occurs before the view transitions phase.
This example uses the astro:before-preparation
event to start a loading indicator and the astro:after-preparation
event to stop it:
This is a simpler version of loading a spinner than the example shown above: if all of the listener’s code can be executed synchronously, there is no need to hook into the loader’s callback.
astro:before-swap
Section titled astro:before-swap
Dodane w:
astro@3.6.0
An event that fires before the new document (which is populated during the preparation phase) replaces the current document. This event occurs inside of the view transition, where the user is still seeing a snapshot of the old page.
This event can be used to make changes before the swap occurs. The newDocument
property on the event represents the incoming document. Here is an example of ensuring the browser’s light or dark mode preference in localStorage
is carried over to the new page:
The astro:before-swap
event can also be used to change the implementation of the swap. The default swap implementation diffs head content, moves persistent elements from the old document to the newDocument
, and then replaces the entire body
with the body of the new document.
At this point of the lifecycle, you could choose to define your own swap implementation, for example to diff the entire contents of the existing document (which some other routers do):
astro:after-swap
Section titled astro:after-swapAn event that fires immediately after the new page replaces the old page. You can listen to this event on the document
and trigger actions that will occur before the new page’s DOM elements render and scripts run.
This event, when listened to on the outgoing page, is useful to pass along and restore any state on the DOM that needs to transfer over to the new page.
This is the latest point in the lifecycle where it is still safe to, for example, add a dark mode class name (<html class="dark-mode">
), though you may wish to do so in an earlier event.
The astro:after-swap
event occurs immediately after the browser history has been updated and the scroll position has been set.
Therefore, one use of targeting this event is to override the default scroll restore for history navigation. The following example resets the horizontal and vertical scroll position to the top left corner of the page for each navigation.
astro:page-load
Section titled astro:page-loadAn 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 for a pre-rendered page and on any subsequent navigation, either forwards or backwards.
You can use this event to run code on every page navigation, or only once ever:
Accessibility
Section titled AccessibilityEnabling client-side routing and animating page transitions both come with accessibility challenges, and Astro aims to make sites opting in to View Transitions as accessible-by-default as possible.
Route announcement
Section titled Route announcement
Dodane w:
astro@3.2.0
The <ViewTransitions />
component includes a route announcer for page navigation during client-side routing. No configuration or action is needed to enable this.
Assistive technologies let visitors know that the page has changed by announcing the new page title after navigation. When using server-side routing with traditional full-page browser refreshes, this happens by default after the new page loads. In client-side routing, the <ViewTransitions />
component performs this action.
To add route announcement to client-side routing, the component adds an element to the new page with the aria-live
attribute set to assertive
. This tells AT (assistive technology) to announce immediately. The component also checks for the following, in priority order, to determine the announcement text:
- The
<title>
, if it exists. - The first
<h1>
it finds. - The
pathname
of the page.
We strongly recommend you always include a <title>
in each page for accessibility.
prefers-reduced-motion
Section titled prefers-reduced-motionAstro’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.
Upgrade to v3.0 from v2.x
Section titled Upgrade to v3.0 from v2.xView transitions are no longer behind an experimental flag in Astro v3.0.
If you had not enabled this experimental flag in Astro 2.x, this will not cause any breaking changes to your project. The new View Transitions API has no effect on your existing code.
If you were previously using experimental view transitions, there may be some breaking changes when you upgrade your Astro project from an earlier version.
Please follow the instructions below as appropriate to upgrade an Astro v2.x project configured with experimental.viewTransitions: true
to v3.0.
Upgrade from experimental.viewTransitions
Section titled Upgrade from experimental.viewTransitionsIf you had previously enabled the experimental flag for view transitions, you will need to update your project for Astro v3.0 which now allows view transitions by default.
Remove experimental.viewTransitions
flag
Section titled Remove experimental.viewTransitions flagRemove the experimental flag:
Update import source
Section titled Update import sourceThe <ViewTransitions />
component has been moved from astro:components
to astro:transitions
. Update the import source across all occurrences in your project.
Update transition:animate
directives
Section titled Update transition:animate directivesChanged: The transition:animate
value morph
has been renamed to initial
. Also, this is no longer the default animation. If no transition:animate
directive is specified, your animations will now default to fade
.
-
Rename any
morph
animations toinitial
. -
To keep any animations that were previously using
morph
by default, explicitly addtransition:animate="initial"
-
You can safely remove any animations explicitly set to
fade
. This is now the default behavior:
Added: Astro also supports a new transition:animate
value, none
. This value can be used on a page’s <html>
element to disable animated full-page transitions on an entire page. This will only override default animation behavior on page elements without an animation directive. You can still set animations on individual elements, and these specific animations will occur.
-
You may now disable all default transitions on an individual page, animating only elements that explicitly use a
transition:animate
directive:
Update event names
Section titled Update event namesThe event astro:load
has been renamed to astro:page-load
. Rename all occurrences in your project.
The event astro:beforeload
has been renamed to astro:after-swap
. Rename all occurrences in your project.