From 14d85747614e184f8c2542706680ff7109dc22f1 Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Tue, 22 Aug 2023 13:15:06 -0400 Subject: [PATCH 01/15] Document the steps that occur during a view transition navigation --- .../docs/en/guides/view-transitions.mdx | 32 ++++++++++++++++--- 1 file changed, 28 insertions(+), 4 deletions(-) diff --git a/src/content/docs/en/guides/view-transitions.mdx b/src/content/docs/en/guides/view-transitions.mdx index 65a07a7607fd7..4cbc9b1adeb0a 100644 --- a/src/content/docs/en/guides/view-transitions.mdx +++ b/src/content/docs/en/guides/view-transitions.mdx @@ -247,6 +247,30 @@ import { ViewTransitions } from 'astro:transitions'; The `morph` animation cannot be simulated in traditional CSS. So any element using this animation will not be animated. ::: +## Navigation steps + +When using the `` router, the following steps are performed as part of navigation: + +1. The user triggers navigation by either: + - Click a `` to another page in your site. + - Clicking the back button. + - Clicking the forward button. +2. The router starts fetching the next page. +3. The router adds the `data-astro-transition` attribute to the HTML element with a value of `'forward'` or `'back'` depending on whether it is back navigation or not. +4. The router calls `document.startViewTransition`. This triggers the browsers own [view transition process](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API#the_view_transition_process). Importantly the browser screenshots the current state of the page. +5. Inside the `startViewTransition` callback, the router performs a __swap__. + 1. The contents of the `` are swapped out. + - 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. + 2. The `` is completely replaced with the new page's body. + 3. Elements marked `transition:persist` are moved over to the new DOM if they exist on the new page. + 4. Scroll position is restored if necessary. + 5. The `astro:after-swap` event is triggered on the `document`. This is the end of the __swap__ process. +6. The router waits for any new stylesheets to load before resolving the transition. +7. The router executes any new scripts added to the page. +8. The `astro:page-load` event fires. This is the end of the navigation process. + ## Script behavior during page navigation When navigating between pages with the `` component, scripts are run in sequential order to match browser behavior. @@ -263,7 +287,7 @@ If you have code that sets up global state, this state will need to take into ac 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` +### `astro:page-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`. @@ -273,14 +297,14 @@ You can use this event to run code on every page navigation, or only once ever: ```astro "{ once: true }" ``` -### `astro:beforeload` +### `astro:after-swap` An event that fires immediately after the new page replaces the old page. You can listen to this event on the `document`. @@ -299,7 +323,7 @@ For example, if you are implementing dark mode support, this event can be used t // Runs on initial navigation setDarkMode(); // Runs on view transitions navigation - document.addEventListener('astro:beforeload', setDarkMode); + document.addEventListener('astro:after-swap', setDarkMode); ``` From 5260dd3463de4b761b7a8978719f576e9aed2ee6 Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Wed, 23 Aug 2023 11:21:17 -0400 Subject: [PATCH 02/15] Document data-astro-reload --- .../docs/en/guides/view-transitions.mdx | 42 +++++++------------ 1 file changed, 15 insertions(+), 27 deletions(-) diff --git a/src/content/docs/en/guides/view-transitions.mdx b/src/content/docs/en/guides/view-transitions.mdx index 4cbc9b1adeb0a..0f9bdf404ff6a 100644 --- a/src/content/docs/en/guides/view-transitions.mdx +++ b/src/content/docs/en/guides/view-transitions.mdx @@ -1,13 +1,13 @@ --- -title: View Transitions (Experimental) +title: View Transitions description: >- - How to enable experimental support for view transitions in your Astro site. + Enable seamless navigation between pages in Astro, with view transitions. i18nReady: true --- import Since from '~/components/Since.astro' -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 supports **opt-in, per-page, view transitions** with just a few simple APIs. View transitions update your page content without the browser's normal, full-page navigation refresh and provide seamless animations between pages. Astro provides a `` routing component that can be added to a single page's `` 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). @@ -18,30 +18,6 @@ Astro's view transitions support is powered by the new [View Transitions](https: - The ability to fully [customize all aspects of transition animation](#customizing-animations), and build your own animations. - [Control over fallback behavior](#fallback-control) for browsers that do not yet support the View Transition APIs. -:::caution -View transitions is an experimental feature enabled in Astro 2.9. The API is subject to change before it is marked as stable. -::: - -## Enabling View Transitions in your Project - -You can enable support for animated page transitions through the experimental `viewTransitions` flag in your Astro config: - -```js title="astro.config.mjs" ins={4-6} -import { defineConfig } from 'astro/config'; - -export default defineConfig({ - experimental: { - viewTransitions: true - } -}); -``` - -:::note -Enabling view transitions support does not automatically convert your entire site into a SPA (Single-page App). By default, every page will still use regular, full-page, browser navigation. - -Add page transitions in Astro with the `` routing component on a per-page basis, or site-wide. -::: - ## Full site view transitions (SPA mode) Import and add the `` component to your common `` 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. @@ -330,3 +306,15 @@ For example, if you are implementing dark mode support, this event can be used t ## `prefers-reduced-motion` Astro's `` component includes a CSS media query that disables *all* view transition animations, including fallback animation, whenever the [`prefer-reduced-motion`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion) setting is detected. Instead, the browser will simply swap the DOM elements without an animation. + +## Preventing client-side navigation + +Once you have enabled client-side routing on a page by adding the `` component, every anchor on the page that links to another page on your site will be navigated via client-side routing. There are some cases where you might want to not navigate via CSR. One example is if it he link is to any non-page, such as a PDF within your `public/` folder. Or an API route that produces an image. + +In these cases you can opt-out of client-side routing on a per-link basis using the `data-astro-reload` attribute like so: + +```html + +``` + +These links will be ignored by the router and a full page navigation will occur. From c4a6ba04a17ac60482d57f0eca1e5203c3c06d5a Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Wed, 23 Aug 2023 14:51:07 -0400 Subject: [PATCH 03/15] Small edits --- src/content/docs/en/guides/view-transitions.mdx | 2 +- src/i18n/en/nav.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/guides/view-transitions.mdx b/src/content/docs/en/guides/view-transitions.mdx index 0f9bdf404ff6a..92eed9f9f8be2 100644 --- a/src/content/docs/en/guides/view-transitions.mdx +++ b/src/content/docs/en/guides/view-transitions.mdx @@ -220,7 +220,7 @@ import { ViewTransitions } from 'astro:transitions'; ``` :::note[known limitations] -The `morph` animation cannot be simulated in traditional CSS. So any element using this animation will not be animated. +The `morph` animation is not simulated by Astro. So any element using this animation will not be animated. ::: ## Navigation steps diff --git a/src/i18n/en/nav.ts b/src/i18n/en/nav.ts index 559771988165c..c7b7d5999b2ea 100644 --- a/src/i18n/en/nav.ts +++ b/src/i18n/en/nav.ts @@ -84,7 +84,7 @@ export default [ { text: 'Middleware', slug: 'guides/middleware', key: 'guides/middleware' }, { text: 'Testing', slug: 'guides/testing', key: 'guides/testing' }, { - text: 'View Transitions (Experimental)', + text: 'View Transitions', slug: 'guides/view-transitions', key: 'guides/view-transitions', }, From e989c70c2ba6dedbff129c528e5f07b77e519f8b Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Thu, 24 Aug 2023 10:59:57 -0400 Subject: [PATCH 04/15] Update src/content/docs/en/guides/view-transitions.mdx Co-authored-by: Nate Moore --- src/content/docs/en/guides/view-transitions.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/view-transitions.mdx b/src/content/docs/en/guides/view-transitions.mdx index 92eed9f9f8be2..78ebc350f56b7 100644 --- a/src/content/docs/en/guides/view-transitions.mdx +++ b/src/content/docs/en/guides/view-transitions.mdx @@ -309,7 +309,7 @@ Astro's `` component includes a CSS media query that disables ## Preventing client-side navigation -Once you have enabled client-side routing on a page by adding the `` component, every anchor on the page that links to another page on your site will be navigated via client-side routing. There are some cases where you might want to not navigate via CSR. One example is if it he link is to any non-page, such as a PDF within your `public/` folder. Or an API route that produces an image. +Once you have enabled client-side routing on a page by adding the `` component, every anchor on the page that links to another page on your site will be navigated via client-side routing. There are some cases where you might want to not navigate via CSR. One example is if the link is to any non-page, such as a PDF within your `public/` folder. Or an API route that produces an image. In these cases you can opt-out of client-side routing on a per-link basis using the `data-astro-reload` attribute like so: From fcd4978a6ae3c651119c8bf9c78bfdcf544126c0 Mon Sep 17 00:00:00 2001 From: Nate Moore Date: Thu, 24 Aug 2023 14:02:58 -0500 Subject: [PATCH 05/15] chore: update built-in animation directives --- .../docs/en/guides/view-transitions.mdx | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/src/content/docs/en/guides/view-transitions.mdx b/src/content/docs/en/guides/view-transitions.mdx index 78ebc350f56b7..6e47c066561b4 100644 --- a/src/content/docs/en/guides/view-transitions.mdx +++ b/src/content/docs/en/guides/view-transitions.mdx @@ -13,7 +13,7 @@ Astro provides a `` routing component that can be added to a Astro's view transitions support is powered by the new [View Transitions](https://developer.chrome.com/docs/web-platform/view-transitions/) browser API and also includes: -- A few [built-in animations](#built-in-animation-directives), such as `slide` and `fade`. +- A few [built-in animations](#built-in-animation-directives), such as `fade`, `slide`, and `none`. - Support for both forwards and backwards navigation animations. - The ability to fully [customize all aspects of transition animation](#customizing-animations), and build your own animations. - [Control over fallback behavior](#fallback-control) for browsers that do not yet support the View Transition APIs. @@ -106,24 +106,26 @@ As a convenient shorthand, `transition:persist` can alternatively take a transit ## 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. +Astro comes with a few built-in animations to override the default `fade` transition. Add the `transition:animate` directive to customize the behavior of your 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. +- `fade` (default): An opinionated crossfade animation, where 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. +- `none`: Disable the browser's default animations. This value can be used on a page's `` element to disable the default fade. - `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: +The example below produces a slide animation for the body content while disabling the browser's fade animation for the rest of the page: ```astro --- import { CommonHead } from '../components/CommonHead.astro'; --- - + + -
// defaults to transition:animate="morph" +
...
@@ -220,7 +222,7 @@ import { ViewTransitions } from 'astro:transitions'; ``` :::note[known limitations] -The `morph` animation is not simulated by Astro. So any element using this animation will not be animated. +The `initial` browser animation is not simulated by Astro. So any element using this animation will not currently be animated. ::: ## Navigation steps From 41e54580be4ce6de5db830cf5f2b9023515eeca1 Mon Sep 17 00:00:00 2001 From: Nate Moore Date: Thu, 24 Aug 2023 14:31:15 -0500 Subject: [PATCH 06/15] add upgrade guide --- .../docs/en/guides/view-transitions.mdx | 53 +++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/src/content/docs/en/guides/view-transitions.mdx b/src/content/docs/en/guides/view-transitions.mdx index 176f76a50d496..bb6af8d854dd1 100644 --- a/src/content/docs/en/guides/view-transitions.mdx +++ b/src/content/docs/en/guides/view-transitions.mdx @@ -320,3 +320,56 @@ In these cases you can opt-out of client-side routing on a per-link basis using ``` These links will be ignored by the router and a full page navigation will occur. + +## Upgrade to v3.0 from v2.x + +View transitions are no longer behind an experimental flag in Astro v3.0. + +These and other accompanying changes may cause 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 to v3.0. + +### Upgrade from `experimental.viewTransitions` + +If 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 + +Remove the experimental flag: + +```js title="astro.config.mjs" del={4-6} +import { defineConfig } from 'astro/config'; + +export default defineConfig({ + experimental: { + viewTransitions: true + } +}); +``` + +#### Update `transition:animate` directives + +The `transition:animate` value `morph` has been renamed to `initial`. Also, this is no longer the default animation. + +```astro title="src/components/MyComponent.astro" del="morph" ins="initial" +
+``` + +If no `transition:animate` directive is specified, your animations will now default to `fade`. + +```astro title="src/components/MyComponent.astro" del="transition:animate=\"fade\"" +
+``` + +Astro also supports a new `transition:animate` value, `none`. This value can be used on a page's `` element to disable animated full-page transitions on an entire page. + +```astro ins="transition:animate=\"none\"" + + + +

Hello world!

+ + +``` + + From 1bf85f64a344144db7a58284f51ff5420b5782fe Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Thu, 24 Aug 2023 15:48:42 -0400 Subject: [PATCH 07/15] Update to explain now event names --- src/content/docs/en/guides/view-transitions.mdx | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/src/content/docs/en/guides/view-transitions.mdx b/src/content/docs/en/guides/view-transitions.mdx index bb6af8d854dd1..63d848fecf054 100644 --- a/src/content/docs/en/guides/view-transitions.mdx +++ b/src/content/docs/en/guides/view-transitions.mdx @@ -372,4 +372,20 @@ Astro also supports a new `transition:animate` value, `none`. This value can be ``` +#### Update event names +The event `astro:load` has been renamed to `astro:page-load`. + +```astro title="src/components/MyComponent.astro" del="astro:load" ins="astro:page-load" + +``` + +The event `astro:beforeload` has been renamed to `astro:after-swap`. + +```astro title="src/components/MyComponent.astro" del="astro:beforeload" ins="astro:after-swap" + +``` From 3c465d61d42cfefabe77ac6da820afe587ceb7ba Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Fri, 25 Aug 2023 08:23:45 -0300 Subject: [PATCH 08/15] Yan `view`ed the document! Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> --- src/content/docs/en/guides/view-transitions.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/docs/en/guides/view-transitions.mdx b/src/content/docs/en/guides/view-transitions.mdx index 63d848fecf054..a5cef129d1cd9 100644 --- a/src/content/docs/en/guides/view-transitions.mdx +++ b/src/content/docs/en/guides/view-transitions.mdx @@ -20,7 +20,7 @@ Astro's view transitions support is powered by the new [View Transitions](https: ## Full site view transitions (SPA mode) -Import and add the `` component to your common `` 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. +Import and add the `` component to your common `` 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 view transitions site-wide by importing and adding this component to a `` Astro component: @@ -109,7 +109,7 @@ As a convenient shorthand, `transition:persist` can alternatively take a transit Astro comes with a few built-in animations to override the default `fade` transition. Add the `transition:animate` directive to customize the behavior of your transitions. - `fade` (default): An opinionated crossfade animation, where 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. +- `initial`: Opt out of Astro's opinionated crossfade animation and use the browser's default styling. - `none`: Disable the browser's default animations. This value can be used on a page's `` element to disable the default fade. - `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. @@ -235,7 +235,7 @@ When using the `` router, the following steps are performed a - Clicking the forward button. 2. The router starts fetching the next page. 3. The router adds the `data-astro-transition` attribute to the HTML element with a value of `'forward'` or `'back'` depending on whether it is back navigation or not. -4. The router calls `document.startViewTransition`. This triggers the browsers own [view transition process](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API#the_view_transition_process). Importantly the browser screenshots the current state of the page. +4. The router calls `document.startViewTransition`. This triggers the browser's own [view transition process](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API#the_view_transition_process). Importantly the browser screenshots the current state of the page. 5. Inside the `startViewTransition` callback, the router performs a __swap__. 1. The contents of the `` are swapped out. - Stylesheet DOM nodes are left in if they exist on the new page, to prevent FOUC. From e39f579a7a5667bf8dd3b530db028483ecf70be3 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Fri, 25 Aug 2023 09:08:38 -0300 Subject: [PATCH 09/15] Sarah's initial suggestions - minor tweaks --- .../docs/en/guides/view-transitions.mdx | 38 +++++++++++++++---- 1 file changed, 30 insertions(+), 8 deletions(-) diff --git a/src/content/docs/en/guides/view-transitions.mdx b/src/content/docs/en/guides/view-transitions.mdx index a5cef129d1cd9..a660452b5e4fc 100644 --- a/src/content/docs/en/guides/view-transitions.mdx +++ b/src/content/docs/en/guides/view-transitions.mdx @@ -1,24 +1,43 @@ --- title: View Transitions description: >- - Enable seamless navigation between pages in Astro, with view transitions. + Enable seamless navigation between pages in Astro with view transitions. i18nReady: true --- import Since from '~/components/Since.astro' -Astro supports **opt-in, per-page, view transitions** with just a few simple APIs. View transitions update your page content without the browser's normal, full-page navigation refresh and provide seamless animations between pages. +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 `` routing component that can be added to a single page's `` 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](https://developer.chrome.com/docs/web-platform/view-transitions/) browser API and also includes: -- A few [built-in animations](#built-in-animation-directives), such as `fade`, `slide`, and `none`. +- A few [built-in animation options](#built-in-animation-directives), such as `fade`, `slide`, and `none`. - Support for both forwards and backwards navigation animations. - The ability to fully [customize all aspects of transition animation](#customizing-animations), and build your own animations. - [Control over fallback behavior](#fallback-control) for browsers that do not yet support the View Transition APIs. -## Full site view transitions (SPA mode) + +:::note +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. +::: + +Opt in to using view transitions on individual pages by importing and adding the `` routing component to `` on every desired page. + +```astro title="src/pages/index.astro" ins={2,7} +--- +import { ViewTransitions } from 'astro:transitions'; +--- + + + My Homepage + + + +

Welcome to my website!

+ + Import and add the `` component to your common `` 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. @@ -106,14 +125,16 @@ As a convenient shorthand, `transition:persist` can alternatively take a transit ## Built-in Animation Directives -Astro comes with a few built-in animations to override the default `fade` transition. Add the `transition:animate` directive to customize the behavior of your transitions. +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, where the old content fades out and the new content fades in. +- `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. -- `none`: Disable the browser's default animations. This value can be used on a page's `` element to disable the default fade. - `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 `` 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 `` 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 fade animation for the rest of the page: +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: ```astro --- @@ -128,6 +149,7 @@ import { CommonHead } from '../components/CommonHead.astro';
...
+
...
From 55fdcc4ca14fd325eb0ccaa881dbb3bc636d9d91 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Fri, 25 Aug 2023 12:17:33 +0000 Subject: [PATCH 10/15] oops, lost a header --- src/content/docs/en/guides/view-transitions.mdx | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/view-transitions.mdx b/src/content/docs/en/guides/view-transitions.mdx index a660452b5e4fc..dbde142f60555 100644 --- a/src/content/docs/en/guides/view-transitions.mdx +++ b/src/content/docs/en/guides/view-transitions.mdx @@ -9,7 +9,9 @@ import Since from '~/components/Since.astro' 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 `` routing component that can be added to a single page's `` 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 provides a `` routing component that can be added to a single page's `` 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)](#full-site-view-transitions-spa-mode). Astro's view transitions support is powered by the new [View Transitions](https://developer.chrome.com/docs/web-platform/view-transitions/) browser API and also includes: @@ -38,6 +40,9 @@ import { ViewTransitions } from 'astro:transitions';

Welcome to my website!

+``` + +## Full site view transitions (SPA mode) Import and add the `` component to your common `` 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. From 894022a86c6b9e2acf1795d7d374d91d40fc63dc Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Fri, 25 Aug 2023 12:49:32 +0000 Subject: [PATCH 11/15] mostly restructuring and tightening existing content --- .../docs/en/guides/view-transitions.mdx | 42 +++++++++++-------- 1 file changed, 24 insertions(+), 18 deletions(-) diff --git a/src/content/docs/en/guides/view-transitions.mdx b/src/content/docs/en/guides/view-transitions.mdx index dbde142f60555..0e2677e330d1f 100644 --- a/src/content/docs/en/guides/view-transitions.mdx +++ b/src/content/docs/en/guides/view-transitions.mdx @@ -18,13 +18,17 @@ Astro's view transitions support is powered by the new [View Transitions](https: - A few [built-in animation options](#built-in-animation-directives), such as `fade`, `slide`, and `none`. - Support for both forwards and backwards navigation animations. - The ability to fully [customize all aspects of transition animation](#customizing-animations), and build your own animations. +- The option to [prevent client-side navigation for non-page links](#preventing-client-side-navigation). - [Control over fallback behavior](#fallback-control) for browsers that do not yet support the View Transition APIs. +- Automatic support for [`prefers-reduced-motion`](#prefers-reduced-motion). :::note 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 + Opt in to using view transitions on individual pages by importing and adding the `` routing component to `` on every desired page. ```astro title="src/pages/index.astro" ins={2,7} @@ -46,7 +50,7 @@ import { ViewTransitions } from 'astro:transitions'; Import and add the `` component to your common `` 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 view transitions site-wide by importing and adding this component to a `` Astro component: +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 `` Astro component: ```astro title="components/CommonHead.astro" ins={2,12} --- @@ -63,7 +67,9 @@ import { ViewTransitions } from 'astro:transitions'; ``` -You can also add view transitions on a per-page basis. Import the `` component and place it directly inside of a page's ``. +No other configuration is necessary to enable Astro's default client-side navigation! + +Use [transition directives](#transition-directives) or [override default client-side navigation](#preventing-client-side-navigation) on individual elements for finer control. ## Transition Directives @@ -76,7 +82,7 @@ Use optional `transition:*` directives on page elements in your `.astro` compone - `transition:persist`: Allows you to override Astro's default replacing old elements for new ones and instead [persist components and HTML elements](#maintaining-state) when navigating to another page. -## Naming a transition +### 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. @@ -90,7 +96,7 @@ In some cases, you may want or need to identify the corresponding view transitio Note that the `transition:name` 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 +### Maintaining State @@ -128,7 +134,7 @@ As a convenient shorthand, `transition:persist` can alternatively take a transit +``` + +These links will be ignored by the router and a full page navigation will occur. + ## Fallback control The `` 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. @@ -336,18 +354,6 @@ For example, if you are implementing dark mode support, this event can be used t Astro's `` component includes a CSS media query that disables *all* view transition animations, including fallback animation, whenever the [`prefer-reduced-motion`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion) setting is detected. Instead, the browser will simply swap the DOM elements without an animation. -## Preventing client-side navigation - -Once you have enabled client-side routing on a page by adding the `` component, every anchor on the page that links to another page on your site will be navigated via client-side routing. There are some cases where you might want to not navigate via CSR. One example is if the link is to any non-page, such as a PDF within your `public/` folder. Or an API route that produces an image. - -In these cases you can opt-out of client-side routing on a per-link basis using the `data-astro-reload` attribute like so: - -```html - -``` - -These links will be ignored by the router and a full page navigation will occur. - ## Upgrade to v3.0 from v2.x View transitions are no longer behind an experimental flag in Astro v3.0. From c298c98bca4f74830e307bb67ac797e6956461cc Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Fri, 25 Aug 2023 13:57:25 +0000 Subject: [PATCH 12/15] Sarah pass at new content --- .../docs/en/guides/view-transitions.mdx | 81 +++++++++++-------- 1 file changed, 48 insertions(+), 33 deletions(-) diff --git a/src/content/docs/en/guides/view-transitions.mdx b/src/content/docs/en/guides/view-transitions.mdx index 0e2677e330d1f..b8a89f633fa6f 100644 --- a/src/content/docs/en/guides/view-transitions.mdx +++ b/src/content/docs/en/guides/view-transitions.mdx @@ -9,7 +9,7 @@ import Since from '~/components/Since.astro' 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 `` routing component that can be added to a single page's `` 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](). +Astro provides a `` routing component that can be added to a single page's `` to control page transitions as you navigate away to another page. It provides a lightweight client-side router that [intercepts navigation](#client-side-navigation-process) 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)](#full-site-view-transitions-spa-mode). @@ -270,26 +270,32 @@ import { ViewTransitions } from 'astro:transitions'; The `initial` browser animation is not simulated by Astro. So any element using this animation will not currently be animated. ::: -## Navigation steps +## Client-side navigation process -When using the `` router, the following steps are performed as part of navigation: +When using the `` router, the following steps occur to produce Astro's client-side navigation: -1. The user triggers navigation by either: - - Click a `` to another page in your site. +1. A visitor to your site triggers navigation by any of the following actions: + - Clicking an `` tag linking internally to another page in your site. - Clicking the back button. - Clicking the forward button. 2. The router starts fetching the next page. -3. The router adds the `data-astro-transition` attribute to the HTML element with a value of `'forward'` or `'back'` depending on whether it is back navigation or not. -4. The router calls `document.startViewTransition`. This triggers the browser's own [view transition process](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API#the_view_transition_process). Importantly the browser screenshots the current state of the page. -5. Inside the `startViewTransition` callback, the router performs a __swap__. - 1. The contents of the `` are swapped out. +3. The router adds the `data-astro-transition` attribute to the HTML element with a value of `'forward'` or `'back'` as appropriate. +4. The router calls `document.startViewTransition`. This triggers the browser's own [view transition process](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API#the_view_transition_process). Importantly, the browser screenshots the current state of the page. +5. Inside the `startViewTransition` callback, the router performs a __swap__, which consists of the following sequence of events: + + - The contents of the `` 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. - 2. The `` is completely replaced with the new page's body. - 3. Elements marked `transition:persist` are moved over to the new DOM if they exist on the new page. - 4. Scroll position is restored if necessary. - 5. The `astro:after-swap` event is triggered on the `document`. This is the end of the __swap__ process. + + - The `` 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 the `document`. This is the end of the __swap__ process. + 6. The router waits for any new stylesheets to load before resolving the transition. 7. The router executes any new scripts added to the page. 8. The `astro:page-load` event fires. This is the end of the navigation process. @@ -358,9 +364,11 @@ Astro's `` component includes a CSS media query that disables View transitions are no longer behind an experimental flag in Astro v3.0. -These and other accompanying changes may cause some breaking changes when you upgrade your Astro project from an earlier version. +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 to v3.0. +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` @@ -382,32 +390,39 @@ export default defineConfig({ #### Update `transition:animate` directives -The `transition:animate` value `morph` has been renamed to `initial`. Also, this is no longer the default animation. +**Changed:** 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`. -```astro title="src/components/MyComponent.astro" del="morph" ins="initial" -
-``` +1. Rename any `morph` animations to `intial`. + ```astro title="src/components/MyComponent.astro" del="morph" ins="initial" +
+ ``` +2. To keep any animations that were previously using `morph` by default, explicitly add `transition:animate="initial"` -If no `transition:animate` directive is specified, your animations will now default to `fade`. + ```astro title="src/components/MyComponent.astro" ins='transition:animate="initial"' +
+ ``` +3. You can safely remove any animations explicitly set to `fade`. This is now the default behavior: -```astro title="src/components/MyComponent.astro" del="transition:animate=\"fade\"" -
-``` + ```astro title="src/components/MyComponent.astro" del="transition:animate=\"fade\"" +
+ ``` -Astro also supports a new `transition:animate` value, `none`. This value can be used on a page's `` element to disable animated full-page transitions on an entire page. +**Added:** Astro also supports a new `transition:animate` value, `none`. This value can be used on a page's `` 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 be occur. -```astro ins="transition:animate=\"none\"" - - - -

Hello world!

- - -``` +4. You may now disable all default transitions on an individual page, animating only elements that explicitly use a `transition:animate` directive: + + ```astro ins="transition:animate=\"none\"" + + + +

Hello world!

+ + + ``` #### Update event names -The event `astro:load` has been renamed to `astro:page-load`. +The event `astro:load` has been renamed to `astro:page-load`. Rename all occurances in your project. ```astro title="src/components/MyComponent.astro" del="astro:load" ins="astro:page-load" ``` -The event `astro:beforeload` has been renamed to `astro:after-swap`. +The event `astro:beforeload` has been renamed to `astro:after-swap`. Rename all occurances in your project. ```astro title="src/components/MyComponent.astro" del="astro:beforeload" ins="astro:after-swap" ``` -The event `astro:beforeload` has been renamed to `astro:after-swap`. Rename all occurances in your project. +The event `astro:beforeload` has been renamed to `astro:after-swap`. Rename all occurrences in your project. ```astro title="src/components/MyComponent.astro" del="astro:beforeload" ins="astro:after-swap"