View transitions
هذا المحتوى غير متوفر بلغتك بعد.
View transitions are animated transitions between different website views. They are a popular design choice for preserving visual continuity as visitors move between states or views of an application.
Astro’s view transitions and client-side routing support is powered by the 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.
- A way to carry HTML elements from the current page to the next during navigation.
- 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.
Differences between browser-native view transitions and Astro’s <ClientRouter />
Section titled “Differences between browser-native view transitions and Astro’s <ClientRouter />”Browser-native, cross-document view transitions can be used in Astro to animate the navigation between documents in a multi-page app (MPA), often providing the experience of client-side routing of single-page applications. They don’t alter the core functionality of a multi-page application, nor do they affect any existing scripts or add additional JavaScript to your page load. They simply add animations.
For enhanced client-side routing and view transition features not yet fully supported by the View Transition API, Astro provides a built-in, lightweight component to enable client-side routing and turn your multi-page app into a single-page app with smooth animations on navigation.
That comes with some benefits, like shared state across pages and persistent elements, and some drawbacks, such as needing to manually reinitialize scripts or state after navigation.
Adding Astro’s built-in <ClientRouter /> component:
- intercepts page navigation and gives you considerable control over this process.
- extends and enhances some View Transition/Navigation API features.
- allows you to configure fallback strategies for when native browser support is lacking.
However, as browser APIs and web standards evolve, using Astro’s <ClientRouter /> for this additional functionality will increasingly become unnecessary. We recommend keeping up with the current state of browser APIs so you can decide whether you still need Astro’s client-side routing for the specific features you use.
Enabling view transitions (SPA mode)
Section titled “Enabling view transitions (SPA mode)”Import and add the <ClientRouter /> 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:
---import { ClientRouter } from "astro:transitions";
type Props = { title: string; description: string };
const { title, description } = Astro.props;---<link rel="icon" type="image/svg+xml" href="/favicon.svg" /><meta name="generator" content={Astro.generator} />
<!-- Primary Meta Tags --><title>{title}</title><meta name="title" content={title} /><meta name="description" content={description} />
<ClientRouter />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 Directives”Astro 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 transition”In 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.
<aside transition:name="hero"><aside transition:name="hero">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”
أُضيفت في:
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.
<video controls muted autoplay transition:persist> <source src="https://ia804502.us.archive.org/33/items/GoldenGa1939_3/GoldenGa1939_3_512kb.mp4" type="video/mp4" /></video>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 component’s internal state of the count will not be reset when navigating back and forth across pages that contain the <Counter /> component with the transition:persist attribute.
<Counter client:load transition:persist initialCount={5} />Not all state can be preserved in this way. The restart of CSS animations and the reload of iframes cannot be avoided during view transitions even when using transition:persist.
You can also manually identify corresponding elements if the island/element is in a different component between the two pages.
<video controls muted autoplay transition:name="media-player" transition:persist/><MyVideo controls muted autoplay transition:name="media-player" transition:persist/>As a convenient shorthand, transition:persist can alternatively take a transition name as a value.
<video controls muted autoplay transition:persist="media-player">transition:persist-props
Section titled “transition:persist-props”
أُضيفت في:
astro@4.5.0
This allows you to control whether or not an island’s props should be persisted upon navigation.
By default, when you add transition:persist to an island, the state is retained upon navigation, but your component will re-render with new props. This is useful, for example, when a component receives page-specific props such as the current page’s title.
You can override this behavior by setting transition:persist-props in addition to transition:persist. Adding this directive will keep an island’s existing props (not re-render with new values) in addition to maintaining its existing state.
Built-in Animation Directives
Section titled “Built-in Animation Directives”Astro 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:
---import CommonHead from "../components/CommonHead.astro";---
<html transition:name="root" transition:animate="none"> <head> <CommonHead /> </head> <body> <header> ... </header> <!-- Override your page default on a single element --> <main transition:animate="slide"> ... </main> </body></html>