From d602e06f8aff5e0d8cb2e01b00cfb8a472221cc3 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Tue, 18 Nov 2025 19:31:21 +0100 Subject: [PATCH 01/18] fix(astro:transitions): add missing docs for available public APIs --- .../reference/modules/astro-transitions.mdx | 392 +++++++++++++++++- 1 file changed, 376 insertions(+), 16 deletions(-) diff --git a/src/content/docs/en/reference/modules/astro-transitions.mdx b/src/content/docs/en/reference/modules/astro-transitions.mdx index a2793a393ce52..fe514d71247b7 100644 --- a/src/content/docs/en/reference/modules/astro-transitions.mdx +++ b/src/content/docs/en/reference/modules/astro-transitions.mdx @@ -23,12 +23,17 @@ For features and usage examples, [see our View Transitions guide](/en/guides/vie ## Imports from `astro:transitions` ```ts -import { ClientRouter, fade, slide } from 'astro:transitions'; +import { + ClientRouter, + createAnimationScope, + fade, + slide, +} from 'astro:transitions'; ``` ### `` -

+

Opt in to using view transitions on individual pages by importing and adding the `` routing component to `` on every desired page. @@ -49,6 +54,18 @@ import { ClientRouter } from 'astro:transitions'; See more about how to [control the router](/en/guides/view-transitions/#router-control) and [add transition directives](/en/guides/view-transitions/#transition-directives) to page elements and components. +The `` component accepts the following props: + +

`fallback`

+ +

+ +**Type:** [`Fallback`](#fallback)
+**Default:** `animate` +

+ +Defines the fallback strategy to use for browsers that do not support the [View Transitions API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API). + ### `fade`

@@ -93,16 +110,80 @@ import { slide } from 'astro:transitions';

``` +### `createAnimationScope()` + +

+ +**Type:** `(transitionName: string, animations: Record) => { scope: string; styles: string; }`
+ +

+ +Defines custom animations with fine-grained control over navigation directions. This takes a transition name and an object to configure animation pairs (e.g., `left`/`right`). This low-level API only generates the `scope` and `styles`. You are still responsible for defining CSS keyframes and associating the appropriate direction with an event listener tied to the [`astro:before-preparation` event](#astrobefore-preparation). + +This can be useful when you need custom directional animations like an interface allowing the user to navigate between north, south, east, and west. + +The following example creates a custom animation for a top-to-bottom navigable gallery, associates the direction in an event listener, and defines the CSS animations: + +```astro title="src/components/Main.astro" +--- +import { createAnimationScope } from "astro:transitions"; + +const { scope, styles } = createAnimationScope("gallery", { + north: { + new: { name: "slideFromTop" }, + old: { name: "slideFromBottom" }, + }, + south: { + new: { name: "slideFromBottom" }, + old: { name: "slideFromTop" }, + }, +}); +--- + +
+ + Go North + Go South +
+ + + + +``` + ## Imports from `astro:transitions/client` ```astro ``` @@ -196,11 +277,11 @@ The element that triggered this navigation, if any. This element will be availab Whether or not view transitions are supported and enabled in the current browser. -### `transitionEnabledOnThisPage` +### `transitionEnabledOnThisPage()`

-**Type:** `boolean`
+**Type:** `() => boolean`

@@ -210,18 +291,19 @@ Whether or not the current page has view transitions enabled for client-side nav

-**Type:** `() => 'none' | 'animate' | 'swap'`
+**Type:** () => Fallback

-Returns the fallback strategy to use in browsers that do not support view transitions. +Returns the fallback strategy to use in browsers that do not support view transitions. This returns `animate` by default when the strategy has not been overridden. -See the guide on [Fallback control](/en/guides/view-transitions/#fallback-control) for how to choose and configure the fallback behavior. +See the guide on [Fallback control](/en/guides/view-transitions/#fallback-control) for how to choose and configure the fallback behavior. ### `swapFunctions`

+**Type:** `object`

@@ -278,6 +360,287 @@ Stores the element in focus on the current page and returns a function that when Replaces the old body with the new body. Then, goes through every element in the old body that should be persisted and have a matching element in the new body and swaps the old element back in place. +### `isTransitionBeforePreparationEvent` + +

+ +**Type:** `(value: any) => boolean`
+ +

+ +Determines whether the given value matches a [`TransitionBeforePreparationEvent`](#transitionbeforepreparationevent). This can be useful when you need to narrow the type of an event in an event listener. + +```astro title="src/pages/index.astro" "isTransitionBeforePreparationEvent" +--- +--- + + +``` + +### `isTransitionBeforeSwapEvent` + +

+ +**Type:** `(value: any) => boolean`
+ +

+ +Determines whether the given value matches a [`TransitionBeforeSwapEvent`](#transitionbeforeswapevent). This can be useful when you need to narrow the type of an event in an event listener. + +```astro title="src/pages/index.astro" "isTransitionBeforeSwapEvent" +--- +--- + + +``` + +### `TRANSITION_BEFORE_PREPARATION` + +

+ +**Type:** `'astro:before-preparation'`
+ +

+ +A constant to avoid writing the `astro:before-preparation` event name in plain text when you define an event. + +```astro title="src/pages/index.astro" "TRANSITION_BEFORE_PREPARATION" +--- +--- + + +``` + +### `TRANSITION_AFTER_PREPARATION` + +

+ +**Type:** `'astro:after-preparation'`
+ +

+ +A constant to avoid writing the `astro:after-preparation` event name in plain text when you define an event. + +```astro title="src/pages/index.astro" "TRANSITION_AFTER_PREPARATION" +--- +--- + + +``` + +### `TRANSITION_BEFORE_SWAP` + +

+ +**Type:** `'astro:before-swap'`
+ +

+ +A constant to avoid writing the `astro:before-swap` event name in plain text when you define an event. + +```astro title="src/pages/index.astro" "TRANSITION_BEFORE_SWAP" +--- +--- + + +``` + +### `TRANSITION_AFTER_SWAP` + +

+ +**Type:** `'astro:after-swap'`
+ +

+ +A constant to avoid writing the `astro:after-swap` event name in plain text when you define an event. + +```astro title="src/pages/index.astro" "TRANSITION_AFTER_SWAP" +--- +--- + + +``` + +### `TRANSITION_PAGE_LOAD` + +

+ +**Type:** `'astro:page-load'`
+ +

+ +A constant to avoid writing the `astro:page-load` event name in plain text when you define an event. + +```astro title="src/pages/index.astro" "TRANSITION_PAGE_LOAD" +--- +--- + + +``` + +## `astro:transitions/client` types + +```astro + +``` + +### `Direction` + +

+ +**Type:** `'forward' | 'back'`
+ +

+ +A union of animation directions: +- `forward`: navigating to the next page in the history or to a new page. +- `back`: navigating to the previous page in the history. + +### `Fallback` + +

+ +**Type:** `'none' | 'animate' | 'swap'`
+ +

+ +A union of fallback strategies to use in browsers that do not support view transitions: +- `animate`: 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. + +Learn more about [controlling the fallback strategy](/en/guides/view-transitions/#fallback-control) with the `ClientRouter`. + +### `NavigationTypeString` + +

+ +**Type:** `'push' | 'replace' | 'traverse'`
+ +

+ +A union of supported history navigation events. + +### `TransitionBeforePreparationEvent` + +

+ +**Type:** `Event`
+ +

+ +Represents an [`astro:before-preparation` event](#astrobefore-preparation). This can be useful to type the event received by a listener: + +```astro title="src/pages/index.astro" "TransitionBeforePreparationEvent" +--- +--- + + +``` + +### `TransitionBeforeSwapEvent` + +

+ +**Type:** `Event`
+ +

+ +Represents an [`astro:before-swap` event](#astrobefore-swap). This can be useful to type the event received by a listener: + +```astro title="src/pages/index.astro" "TransitionBeforeSwapEvent" +--- +--- + + +``` + ## Lifecycle events ### `astro:before-preparation` event @@ -342,7 +705,7 @@ When view transitions is enabled on the page, code that would normally execute o

-**Type:** `URL` +**Type:** `any`

Arbitrary data defined during navigation. @@ -373,7 +736,7 @@ The document for the next page in the navigation. The contents of this document

-**Type:** `'push' | 'replace' | 'traverse'` +**Type:** [`NavigationTypeString`](#navigationtypestring)

Which kind of history navigation is happening. @@ -389,10 +752,7 @@ Which kind of history navigation is happening. **Type:** `Direction`

-The direction of the transition. -- `forward`: navigating to the next page in the history or to a new page. -- `back`: navigating to the previous page in the history. -- Anything else some other listener might have set. +The direction of the transition. This can be a predefined [`Direction`](#direction) or anything else some other listener might have set. #### `from` From 33776c49fba81aedb9245fc2c996c8ad413332e1 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Tue, 18 Nov 2025 21:38:47 +0100 Subject: [PATCH 02/18] fix/add links --- .../docs/en/reference/modules/astro-transitions.mdx | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/src/content/docs/en/reference/modules/astro-transitions.mdx b/src/content/docs/en/reference/modules/astro-transitions.mdx index fe514d71247b7..2c3bdeacc1692 100644 --- a/src/content/docs/en/reference/modules/astro-transitions.mdx +++ b/src/content/docs/en/reference/modules/astro-transitions.mdx @@ -264,8 +264,8 @@ This option mimics the [`state` option](https://developer.mozilla.org/en-US/docs

The element that triggered this navigation, if any. This element will be available in the following events: -- `astro:before-preparation` -- `astro:before-swap` +- [`astro:before-preparation`](#astrobefore-preparation-event) +- [`astro:before-swap`](#astrobefore-swap-event) ### `supportsViewTransitions` @@ -651,7 +651,7 @@ This event has the attributes: - [`info`](#info) - [`sourceElement`](#sourceelement) - [`navigationType`](#navigationtype) -- [`direction`](#direction) +- [`direction`](#direction-1) - [`from`](#from) - [`to`](#to) - [`formData`](#formdata) @@ -677,7 +677,7 @@ This event has the attributes: - [`info`](#info) - [`sourceElement`](#sourceelement) - [`navigationType`](#navigationtype) -- [`direction`](#direction) +- [`direction`](#direction-1) - [`from`](#from) - [`to`](#to) - [`viewTransition`](#viewtransition) @@ -742,8 +742,7 @@ The document for the next page in the navigation. The contents of this document Which kind of history navigation is happening. - `push`: a new `NavigationHistoryEntry` is being created for the new page. - `replace`: the current `NavigationHistoryEntry` is being replaced with an entry for the new page. -- `traverse`: no `NavigationHistoryEntry` is created. The position in the history is changing. - The direction of the traversal is given on the [`direction` attribute](#direction) +- `traverse`: no `NavigationHistoryEntry` is created. The position in the history is changing. The direction of the traversal is given on the [`direction` attribute](#direction-1). #### `direction` From 1621175b5821ab343b6224e7a7546db9fdb900ca Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Tue, 18 Nov 2025 21:49:57 +0100 Subject: [PATCH 03/18] use ReadMore with existing content --- .../en/reference/modules/astro-transitions.mdx | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/src/content/docs/en/reference/modules/astro-transitions.mdx b/src/content/docs/en/reference/modules/astro-transitions.mdx index 2c3bdeacc1692..6aad8321ef2a0 100644 --- a/src/content/docs/en/reference/modules/astro-transitions.mdx +++ b/src/content/docs/en/reference/modules/astro-transitions.mdx @@ -657,7 +657,7 @@ This event has the attributes: - [`formData`](#formdata) - [`loader()`](#loader) -Read more about how to use this event on the [View Transitions guide](/en/guides/view-transitions/#astrobefore-preparation). +Read more about how to use this event on the [View Transitions guide](/en/guides/view-transitions/#astrobefore-preparation). ### `astro:after-preparation` event @@ -665,7 +665,7 @@ An event dispatched after the next page in a navigation using View Transitions r This event has no attributes. -Read more about how to use this event on the [View Transitions guide](/en/guides/view-transitions/#astroafter-preparation). +Read more about how to use this event on the [View Transitions guide](/en/guides/view-transitions/#astroafter-preparation). ### `astro:before-swap` event @@ -683,7 +683,7 @@ This event has the attributes: - [`viewTransition`](#viewtransition) - [`swap()`](#swap) -Read more about how to use this event on the [View Transitions guide](/en/guides/view-transitions/#astrobefore-swap). +Read more about how to use this event on the [View Transitions guide](/en/guides/view-transitions/#astrobefore-swap). ### `astro:after-swap` event @@ -809,14 +809,12 @@ The view transition object used in this navigation. On browsers that do not supp **Type:** `() => void`

-Implementation of the document swap logic. - -Read more about [building a custom swap function](/en/guides/view-transitions/#building-a-custom-swap-function) in the View Transitions guide. - -By default, this implementation will call the following functions in order: +Calls the default document swap logic. By default, this implementation will call the following functions in order: 1. [`deselectScripts()`](#deselectscripts) 2. [`swapRootAttributes()`](#swaprootattributes) 3. [`swapHeadElements()`](#swapheadelements) 4. [`saveFocus()`](#savefocus) 5. [`swapBodyElement()`](#swapbodyelement) + +Read more about [building a custom swap function](/en/guides/view-transitions/#building-a-custom-swap-function) in the View Transitions guide. From ab93cffd0fdd5d64ef5b6f6195aa91f203a9aaa4 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Tue, 18 Nov 2025 21:50:23 +0100 Subject: [PATCH 04/18] fix `direction` type, I write about the change but didn't update docs! --- src/content/docs/en/reference/modules/astro-transitions.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/modules/astro-transitions.mdx b/src/content/docs/en/reference/modules/astro-transitions.mdx index 6aad8321ef2a0..9a1d1ce30d995 100644 --- a/src/content/docs/en/reference/modules/astro-transitions.mdx +++ b/src/content/docs/en/reference/modules/astro-transitions.mdx @@ -748,7 +748,7 @@ Which kind of history navigation is happening.

-**Type:** `Direction` +**Type:** `string`

The direction of the transition. This can be a predefined [`Direction`](#direction) or anything else some other listener might have set. From 752e69f1c069bb0088535f95ccadac42aa06a1ca Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Tue, 18 Nov 2025 22:02:35 +0100 Subject: [PATCH 05/18] add precision about event attributes availability --- .../en/reference/modules/astro-transitions.mdx | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/src/content/docs/en/reference/modules/astro-transitions.mdx b/src/content/docs/en/reference/modules/astro-transitions.mdx index 9a1d1ce30d995..6ac7a608d5de4 100644 --- a/src/content/docs/en/reference/modules/astro-transitions.mdx +++ b/src/content/docs/en/reference/modules/astro-transitions.mdx @@ -701,6 +701,8 @@ When view transitions is enabled on the page, code that would normally execute o

+The following attributes are common to both the [`astro:before-preparation`](#astrobefore-preparation-event) and [`astro:before-swap`](#astrobefore-swap-event) events, except for some that are only available with one or the other. + #### `info`

@@ -753,6 +755,8 @@ Which kind of history navigation is happening. The direction of the transition. This can be a predefined [`Direction`](#direction) or anything else some other listener might have set. +In the [`astro:before-preparation` event](#astrobefore-swap-event), the value is writable and accepts any `string`. In the [`astro:before-swap` event](#astrobefore-swap-event), the value is readonly. + #### `from`

@@ -775,7 +779,8 @@ The URL of the page being navigated to. This property can be modified, the value

-**Type:** `FormData | undefined` +**Type:** `FormData | undefined`
+**Available in:** [`astro:before-preparation` event](#astrobefore-preparation-event)

A `FormData` object for `POST` requests. @@ -788,7 +793,8 @@ When submitting an HTML form with view transitions enabled, this field is automa

-**Type:** `() => Promise` +**Type:** `() => Promise`
+**Available in:** [`astro:before-preparation` event](#astrobefore-preparation-event)

Implementation of the following phase in the navigation (loading the next page). This implementation can be overridden to add extra behavior. @@ -797,7 +803,8 @@ Implementation of the following phase in the navigation (loading the next page).

-**Type:** [`ViewTransition`](https://developer.mozilla.org/en-US/docs/Web/API/ViewTransition) +**Type:** [`ViewTransition`](https://developer.mozilla.org/en-US/docs/Web/API/ViewTransition)
+**Available in:** [`astro:before-swap` event](#astrobefore-swap-event)

The view transition object used in this navigation. On browsers that do not support the [View Transitions API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API), this is an object implementing the same API for convenience but without the DOM integration. @@ -806,7 +813,8 @@ The view transition object used in this navigation. On browsers that do not supp

-**Type:** `() => void` +**Type:** `() => void`
+**Available in:** [`astro:before-swap` event](#astrobefore-swap-event)

Calls the default document swap logic. By default, this implementation will call the following functions in order: From a8eb42042848487cfc716e18f24b7de0b85b5662 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Tue, 18 Nov 2025 22:14:13 +0100 Subject: [PATCH 06/18] small rewording on existing content --- .../docs/en/reference/modules/astro-transitions.mdx | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/src/content/docs/en/reference/modules/astro-transitions.mdx b/src/content/docs/en/reference/modules/astro-transitions.mdx index 6ac7a608d5de4..ab71724ffa05f 100644 --- a/src/content/docs/en/reference/modules/astro-transitions.mdx +++ b/src/content/docs/en/reference/modules/astro-transitions.mdx @@ -196,7 +196,7 @@ const { scope, styles } = createAnimationScope("gallery", {

-A function that executes a navigation to the given `href` using the View Transitions API. +Executes a navigation to the given `href` using the View Transitions API. This function signature is based on the [`navigate` function from the browser Navigation API](https://developer.mozilla.org/en-US/docs/Web/API/Navigation/navigate). Although based on the Navigation API, this function is implemented on top of the [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) to allow for navigation without reloading the page. @@ -225,9 +225,7 @@ This option follows the [`history` option](https://developer.mozilla.org/en-US/d

-A `FormData` object for `POST` requests. - -When this option is provided, the requests to the navigation target page will be sent as a `POST` request with the form data object as the content. +When provided, the requests to the navigation target page will be sent as a `POST` request with the `FormData` object as the content. Submitting an HTML form with view transitions enabled will use this method instead of the default navigation with page reload. Calling this method allows triggering the same behavior programmatically. @@ -783,9 +781,7 @@ The URL of the page being navigated to. This property can be modified, the value **Available in:** [`astro:before-preparation` event](#astrobefore-preparation-event)

-A `FormData` object for `POST` requests. - -When this attribute is set, a `POST` request will be sent to the [`to` URL](#to) with the given form data object as the content instead of the normal `GET` request. +When set, a `POST` request will be sent to the [`to` URL](#to) with the given `FormData` object as the content instead of the normal `GET` request. When submitting an HTML form with view transitions enabled, this field is automatically set to the data in the form. When using the [`navigate()` function](#navigate), this value is the same as given in the options. From 6dadf515e65ebaa1a153b98df391e6059d7cd39c Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Wed, 19 Nov 2025 14:16:29 +0100 Subject: [PATCH 07/18] update/add links in the view transitions guide --- .../docs/en/guides/view-transitions.mdx | 23 ++++++------------- 1 file changed, 7 insertions(+), 16 deletions(-) diff --git a/src/content/docs/en/guides/view-transitions.mdx b/src/content/docs/en/guides/view-transitions.mdx index 5ca16210a1291..f2c1ea2415e08 100644 --- a/src/content/docs/en/guides/view-transitions.mdx +++ b/src/content/docs/en/guides/view-transitions.mdx @@ -3,6 +3,7 @@ title: View transitions description: Enable seamless navigation between pages in Astro with view transitions. i18nReady: true --- +import ReadMore from '~/components/ReadMore.astro'; import Since from '~/components/Since.astro' import { Steps } from '@astrojs/starlight/components' @@ -319,7 +320,7 @@ Links with the `data-astro-reload` attribute will be ignored by the router and a ### Trigger navigation -You can also trigger client-side navigation via events not normally listened to by the `` 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](/en/reference/directives-reference/#client-directives). +You can also trigger client-side navigation via events not normally listened to by the `` router using [`navigate()`](/en/reference/modules/astro-transitions/#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](/en/reference/directives-reference/#client-directives). The following example shows an Astro component that navigates a visitor to another page they select from a menu: @@ -390,27 +391,17 @@ import { ClientRouter } from "astro:transitions"; ``` -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 use `history.pushState` to create a new entry in the browser history. - - `"replace"`: the router will use `history.replaceState` to update the URL without adding a new entry into navigation. - - `"auto"` (default): the router will attempt `history.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`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) object for `POST` 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. +See the `astro:transitions` reference for more information about the [`navigate()` options](/en/reference/modules/astro-transitions/#navigate). + ### Replace entries in the browser history Normally, 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 `` router allows you to overwrite history entries by adding the `data-astro-history` attribute to any individual `` tag. -The `data-astro-history` attribute can be set to the same three values as the [`history` option of the `navigate()` function](#trigger-navigation): - -`data-astro-history`: `"push"` | `"replace"` | `"auto"` +The `data-astro-history` attribute can be set to the same three values as the [`history` option of the `navigate()` function](/en/reference/modules/astro-transitions/#history-option): - `"push"`: the router will use `history.pushState` to create a new entry in the browser history. - `"replace"`: the router will use `history.replaceState` to update the URL without adding a new entry into navigation. @@ -605,7 +596,7 @@ This event is used: - 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 either `forward` or `backward`) 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. +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](/en/reference/modules/astro-transitions/#loader) in this way allows asynchronous execution of code. ```astro +```ts +import { + getFallback, + isTransitionBeforePreparationEvent, + isTransitionBeforeSwapEvent, + navigate, + supportsViewTransitions, + swapFunctions, + transitionEnabledOnThisPage, + TRANSITION_AFTER_PREPARATION, + TRANSITION_AFTER_SWAP, + TRANSITION_BEFORE_PREPARATION, + TRANSITION_BEFORE_SWAP, + TRANSITION_PAGE_LOAD, +} from 'astro:transitions/client'; ``` ### `navigate()` @@ -431,11 +429,11 @@ A constant to avoid writing the `astro:before-preparation` event name in plain t --- ``` @@ -454,11 +452,11 @@ A constant to avoid writing the `astro:after-preparation` event name in plain te --- ``` @@ -477,11 +475,11 @@ A constant to avoid writing the `astro:before-swap` event name in plain text whe --- ``` @@ -500,11 +498,11 @@ A constant to avoid writing the `astro:after-swap` event name in plain text when --- ``` @@ -523,27 +521,25 @@ A constant to avoid writing the `astro:page-load` event name in plain text when --- ``` ## `astro:transitions/client` types -```astro - +```ts +import type { + Direction, + Fallback, + NavigationTypeString, + Options, + TransitionBeforePreparationEvent, + TransitionBeforeSwapEvent, +} from 'astro:transitions/client'; ``` ### `Direction` From bc9c53ba74f16ebe1fa93dfde4bcd91ec28914ff Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Wed, 26 Nov 2025 14:28:18 +0100 Subject: [PATCH 10/18] update `direction` description based on Martin feedback + fix link --- src/content/docs/en/reference/modules/astro-transitions.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/docs/en/reference/modules/astro-transitions.mdx b/src/content/docs/en/reference/modules/astro-transitions.mdx index 0f47aec8d19f8..2d72cbedb011a 100644 --- a/src/content/docs/en/reference/modules/astro-transitions.mdx +++ b/src/content/docs/en/reference/modules/astro-transitions.mdx @@ -775,9 +775,9 @@ Which kind of history navigation is happening. **Type:** `string`

-The direction of the transition. This can be a predefined [`Direction`](#direction) or anything else some other listener might have set. - -In the [`astro:before-preparation` event](#astrobefore-swap-event), the value is writable and accepts any `string`. In the [`astro:before-swap` event](#astrobefore-swap-event), the value is readonly. +The direction of the transition: +* In an [`astro:before-preparation` event](#astrobefore-preparation-event), this can be used to define custom directions. The property is writable and accepts any string. +* In an [`astro:before-swap` event](#astrobefore-swap-event), this can be used to retrieve the transition direction. The property is readonly and its value can be a predefined [`Direction`](#direction) or any string that an `astro:before-preparation` event listener might have set. #### `from` From 14d134fe3b036080526f379d3ee67f54aaacce42 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Fri, 28 Nov 2025 22:25:12 +0100 Subject: [PATCH 11/18] Apply Martin fixes to createAnimationScope Co-authored-by: Martin Trapp <94928215+martrapp@users.noreply.github.com> --- .../reference/modules/astro-transitions.mdx | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/src/content/docs/en/reference/modules/astro-transitions.mdx b/src/content/docs/en/reference/modules/astro-transitions.mdx index fd2d9c5a4d024..257b9ecfd4c57 100644 --- a/src/content/docs/en/reference/modules/astro-transitions.mdx +++ b/src/content/docs/en/reference/modules/astro-transitions.mdx @@ -131,17 +131,17 @@ import { createAnimationScope } from "astro:transitions"; const { scope, styles } = createAnimationScope("gallery", { north: { new: { name: "slideFromTop" }, - old: { name: "slideFromBottom" }, + old: { name: "slideToBottom" }, }, south: { new: { name: "slideFromBottom" }, - old: { name: "slideFromTop" }, + old: { name: "slideToTop" }, }, }); ---
- + ``` From 32b0f508f945d51c1185d87a09aeadc462389058 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Thu, 4 Dec 2025 13:47:38 +0100 Subject: [PATCH 12/18] remove `createAnimationScope`` --- .../reference/modules/astro-transitions.mdx | 61 ------------------- 1 file changed, 61 deletions(-) diff --git a/src/content/docs/en/reference/modules/astro-transitions.mdx b/src/content/docs/en/reference/modules/astro-transitions.mdx index 257b9ecfd4c57..a93d04e3e0232 100644 --- a/src/content/docs/en/reference/modules/astro-transitions.mdx +++ b/src/content/docs/en/reference/modules/astro-transitions.mdx @@ -25,7 +25,6 @@ For features and usage examples, [see our View Transitions guide](/en/guides/vie ```ts import { ClientRouter, - createAnimationScope, fade, slide, } from 'astro:transitions'; @@ -110,66 +109,6 @@ import { slide } from 'astro:transitions';
``` -### `createAnimationScope()` - -

- -**Type:** `(transitionName: string, animations: Record) => { scope: string; styles: string; }`
- -

- -Defines custom animations with fine-grained control over navigation directions. This takes a transition name and an object to configure animation pairs (e.g., `left`/`right`). This low-level API only generates the `scope` and `styles`. You are still responsible for defining CSS keyframes and associating the appropriate direction with an event listener tied to the [`astro:before-preparation` event](#astrobefore-preparation). - -This can be useful when you need custom directional animations like an interface allowing the user to navigate between north, south, east, and west. - -The following example creates a custom animation for a top-to-bottom navigable gallery, associates the direction in an event listener, and defines the CSS animations: - -```astro title="src/components/Main.astro" ---- -import { createAnimationScope } from "astro:transitions"; - -const { scope, styles } = createAnimationScope("gallery", { - north: { - new: { name: "slideFromTop" }, - old: { name: "slideToBottom" }, - }, - south: { - new: { name: "slideFromBottom" }, - old: { name: "slideToTop" }, - }, -}); ---- - -
- -``` - ## Imports from `astro:transitions/client` ```ts From 74d9bd94e300d393d4c058544fa981eeaaf1826c Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Thu, 4 Dec 2025 15:35:26 +0100 Subject: [PATCH 13/18] add a Deprecated imports sections --- .../reference/modules/astro-transitions.mdx | 25 ++++++++++++------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/src/content/docs/en/reference/modules/astro-transitions.mdx b/src/content/docs/en/reference/modules/astro-transitions.mdx index a93d04e3e0232..1d5cd6b4da125 100644 --- a/src/content/docs/en/reference/modules/astro-transitions.mdx +++ b/src/content/docs/en/reference/modules/astro-transitions.mdx @@ -114,12 +114,13 @@ import { slide } from 'astro:transitions'; ```ts import { getFallback, - isTransitionBeforePreparationEvent, - isTransitionBeforeSwapEvent, navigate, supportsViewTransitions, swapFunctions, transitionEnabledOnThisPage, + /* The following are schedule for deprecation in v6: */ + isTransitionBeforePreparationEvent, + isTransitionBeforeSwapEvent, TRANSITION_AFTER_PREPARATION, TRANSITION_AFTER_SWAP, TRANSITION_BEFORE_PREPARATION, @@ -300,7 +301,13 @@ Stores the element in focus on the current page and returns a function that when Replaces the old body with the new body. Then, goes through every element in the old body that should be persisted and have a matching element in the new body and swaps the old element back in place. -### `isTransitionBeforePreparationEvent` +### Deprecated imports + +:::caution[Schedule for deprecation] +The following imports are schedule for deprecation in v6. You can still use them in your project, but you may prefer to update your code now. +::: + +#### `isTransitionBeforePreparationEvent()`

@@ -329,7 +336,7 @@ Determines whether the given value matches a [`TransitionBeforePreparationEvent` ``` -### `isTransitionBeforeSwapEvent` +#### `isTransitionBeforeSwapEvent()`

@@ -358,7 +365,7 @@ Determines whether the given value matches a [`TransitionBeforeSwapEvent`](#tran ``` -### `TRANSITION_BEFORE_PREPARATION` +#### `TRANSITION_BEFORE_PREPARATION`

@@ -381,7 +388,7 @@ A constant to avoid writing the `astro:before-preparation` event name in plain t ``` -### `TRANSITION_AFTER_PREPARATION` +#### `TRANSITION_AFTER_PREPARATION`

@@ -404,7 +411,7 @@ A constant to avoid writing the `astro:after-preparation` event name in plain te ``` -### `TRANSITION_BEFORE_SWAP` +#### `TRANSITION_BEFORE_SWAP`

@@ -427,7 +434,7 @@ A constant to avoid writing the `astro:before-swap` event name in plain text whe ``` -### `TRANSITION_AFTER_SWAP` +#### `TRANSITION_AFTER_SWAP`

@@ -450,7 +457,7 @@ A constant to avoid writing the `astro:after-swap` event name in plain text when ``` -### `TRANSITION_PAGE_LOAD` +#### `TRANSITION_PAGE_LOAD`

From 8da069d21ac6cde3e2590a40ea07dff6f3edbbd4 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Thu, 4 Dec 2025 15:51:00 +0100 Subject: [PATCH 14/18] fix links --- src/content/docs/en/reference/modules/astro-transitions.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/reference/modules/astro-transitions.mdx b/src/content/docs/en/reference/modules/astro-transitions.mdx index 1d5cd6b4da125..ee04d4197ef6b 100644 --- a/src/content/docs/en/reference/modules/astro-transitions.mdx +++ b/src/content/docs/en/reference/modules/astro-transitions.mdx @@ -538,7 +538,7 @@ A union of supported history navigation events.

-Represents an [`astro:before-preparation` event](#astrobefore-preparation). This can be useful to type the event received by a listener: +Represents an [`astro:before-preparation` event](#astrobefore-preparation-event). This can be useful to type the event received by a listener: ```astro title="src/pages/index.astro" "TransitionBeforePreparationEvent" --- @@ -566,7 +566,7 @@ Represents an [`astro:before-preparation` event](#astrobefore-preparation). This

-Represents an [`astro:before-swap` event](#astrobefore-swap). This can be useful to type the event received by a listener: +Represents an [`astro:before-swap` event](#astrobefore-swap-event). This can be useful to type the event received by a listener: ```astro title="src/pages/index.astro" "TransitionBeforeSwapEvent" --- From d82ce257b7fd9888ca3bdee178cc1e185d3f8c7a Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Thu, 4 Dec 2025 16:14:11 +0100 Subject: [PATCH 15/18] hide the deprecated imports from the toc? --- .../en/reference/modules/astro-transitions.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/content/docs/en/reference/modules/astro-transitions.mdx b/src/content/docs/en/reference/modules/astro-transitions.mdx index ee04d4197ef6b..c92c09d10c68e 100644 --- a/src/content/docs/en/reference/modules/astro-transitions.mdx +++ b/src/content/docs/en/reference/modules/astro-transitions.mdx @@ -307,7 +307,7 @@ Replaces the old body with the new body. Then, goes through every element in the The following imports are schedule for deprecation in v6. You can still use them in your project, but you may prefer to update your code now. ::: -#### `isTransitionBeforePreparationEvent()` +

`isTransitionBeforePreparationEvent()`

@@ -336,7 +336,7 @@ Determines whether the given value matches a [`TransitionBeforePreparationEvent` ``` -#### `isTransitionBeforeSwapEvent()` +

`isTransitionBeforeSwapEvent()`

@@ -365,7 +365,7 @@ Determines whether the given value matches a [`TransitionBeforeSwapEvent`](#tran ``` -#### `TRANSITION_BEFORE_PREPARATION` +

`TRANSITION_BEFORE_PREPARATION`

@@ -388,7 +388,7 @@ A constant to avoid writing the `astro:before-preparation` event name in plain t ``` -#### `TRANSITION_AFTER_PREPARATION` +

`TRANSITION_AFTER_PREPARATION`

@@ -411,7 +411,7 @@ A constant to avoid writing the `astro:after-preparation` event name in plain te ``` -#### `TRANSITION_BEFORE_SWAP` +

`TRANSITION_BEFORE_SWAP`

@@ -434,7 +434,7 @@ A constant to avoid writing the `astro:before-swap` event name in plain text whe ``` -#### `TRANSITION_AFTER_SWAP` +

`TRANSITION_AFTER_SWAP`

@@ -457,7 +457,7 @@ A constant to avoid writing the `astro:after-swap` event name in plain text when ``` -#### `TRANSITION_PAGE_LOAD` +

`TRANSITION_PAGE_LOAD`

From 794ecd12c88de20099fe0aff3845c3b1e3d48893 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Thu, 4 Dec 2025 22:28:31 +0100 Subject: [PATCH 16/18] Thanks Sarah Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> --- .../docs/en/reference/modules/astro-transitions.mdx | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/src/content/docs/en/reference/modules/astro-transitions.mdx b/src/content/docs/en/reference/modules/astro-transitions.mdx index c92c09d10c68e..5850436ce4a80 100644 --- a/src/content/docs/en/reference/modules/astro-transitions.mdx +++ b/src/content/docs/en/reference/modules/astro-transitions.mdx @@ -118,7 +118,7 @@ import { supportsViewTransitions, swapFunctions, transitionEnabledOnThisPage, - /* The following are schedule for deprecation in v6: */ + /* The following are scheduled for deprecation in v6: */ isTransitionBeforePreparationEvent, isTransitionBeforeSwapEvent, TRANSITION_AFTER_PREPARATION, @@ -233,10 +233,11 @@ Whether or not the current page has view transitions enabled for client-side nav

**Type:** () => Fallback
+**Default:** `animate`

-Returns the fallback strategy to use in browsers that do not support view transitions. This returns `animate` by default when the strategy has not been overridden. +Returns the fallback strategy to use (`animate` by default) in browsers that do not support view transitions. See the guide on [Fallback control](/en/guides/view-transitions/#fallback-control) for how to choose and configure the fallback behavior. @@ -303,8 +304,8 @@ Replaces the old body with the new body. Then, goes through every element in the ### Deprecated imports -:::caution[Schedule for deprecation] -The following imports are schedule for deprecation in v6. You can still use them in your project, but you may prefer to update your code now. +:::caution[Scheduled for deprecation] +The following imports are scheduled for deprecation in v6. You can still use them in your project, but you may prefer to update your code now. :::

`isTransitionBeforePreparationEvent()`

From f6580ac3c91363f8d947aaf1df591a8324ca07af Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Thu, 4 Dec 2025 22:36:00 +0100 Subject: [PATCH 17/18] revert `formData` description changes --- src/content/docs/en/reference/modules/astro-transitions.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/modules/astro-transitions.mdx b/src/content/docs/en/reference/modules/astro-transitions.mdx index 5850436ce4a80..8f71dbb47fa3f 100644 --- a/src/content/docs/en/reference/modules/astro-transitions.mdx +++ b/src/content/docs/en/reference/modules/astro-transitions.mdx @@ -168,7 +168,9 @@ This option follows the [`history` option](https://developer.mozilla.org/en-US/d

-When provided, the requests to the navigation target page will be sent as a `POST` request with the `FormData` object as the content. +A `FormData` object for `POST` requests. + +When this option is provided, the requests to the navigation target page will be sent as a `POST` request with the form data object as the content. Submitting an HTML form with view transitions enabled will use this method instead of the default navigation with page reload. Calling this method allows triggering the same behavior programmatically. From 1ad0374af4d829761ea62342d5be3ba05a65d247 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Thu, 4 Dec 2025 22:38:43 +0100 Subject: [PATCH 18/18] add individual deprecation warnings --- .../reference/modules/astro-transitions.mdx | 30 +++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/reference/modules/astro-transitions.mdx b/src/content/docs/en/reference/modules/astro-transitions.mdx index 8f71dbb47fa3f..8f5cdf417f372 100644 --- a/src/content/docs/en/reference/modules/astro-transitions.mdx +++ b/src/content/docs/en/reference/modules/astro-transitions.mdx @@ -306,9 +306,7 @@ Replaces the old body with the new body. Then, goes through every element in the ### Deprecated imports -:::caution[Scheduled for deprecation] The following imports are scheduled for deprecation in v6. You can still use them in your project, but you may prefer to update your code now. -:::

`isTransitionBeforePreparationEvent()`

@@ -318,6 +316,10 @@ The following imports are scheduled for deprecation in v6. You can still use the

+:::caution[Scheduled for deprecation] +This function is scheduled for deprecation in v6. You can still use it in your project, but you may prefer to update your code now. +::: + Determines whether the given value matches a [`TransitionBeforePreparationEvent`](#transitionbeforepreparationevent). This can be useful when you need to narrow the type of an event in an event listener. ```astro title="src/pages/index.astro" "isTransitionBeforePreparationEvent" @@ -347,6 +349,10 @@ Determines whether the given value matches a [`TransitionBeforePreparationEvent`

+:::caution[Scheduled for deprecation] +This function is scheduled for deprecation in v6. You can still use it in your project, but you may prefer to update your code now. +::: + Determines whether the given value matches a [`TransitionBeforeSwapEvent`](#transitionbeforeswapevent). This can be useful when you need to narrow the type of an event in an event listener. ```astro title="src/pages/index.astro" "isTransitionBeforeSwapEvent" @@ -376,6 +382,10 @@ Determines whether the given value matches a [`TransitionBeforeSwapEvent`](#tran

+:::caution[Scheduled for deprecation] +This constant is scheduled for deprecation in v6. You can still use it in your project, but you may prefer to update your code now. +::: + A constant to avoid writing the `astro:before-preparation` event name in plain text when you define an event. ```astro title="src/pages/index.astro" "TRANSITION_BEFORE_PREPARATION" @@ -399,6 +409,10 @@ A constant to avoid writing the `astro:before-preparation` event name in plain t

+:::caution[Scheduled for deprecation] +This constant is scheduled for deprecation in v6. You can still use it in your project, but you may prefer to update your code now. +::: + A constant to avoid writing the `astro:after-preparation` event name in plain text when you define an event. ```astro title="src/pages/index.astro" "TRANSITION_AFTER_PREPARATION" @@ -422,6 +436,10 @@ A constant to avoid writing the `astro:after-preparation` event name in plain te

+:::caution[Scheduled for deprecation] +This constant is scheduled for deprecation in v6. You can still use it in your project, but you may prefer to update your code now. +::: + A constant to avoid writing the `astro:before-swap` event name in plain text when you define an event. ```astro title="src/pages/index.astro" "TRANSITION_BEFORE_SWAP" @@ -445,6 +463,10 @@ A constant to avoid writing the `astro:before-swap` event name in plain text whe

+:::caution[Scheduled for deprecation] +This constant is scheduled for deprecation in v6. You can still use it in your project, but you may prefer to update your code now. +::: + A constant to avoid writing the `astro:after-swap` event name in plain text when you define an event. ```astro title="src/pages/index.astro" "TRANSITION_AFTER_SWAP" @@ -468,6 +490,10 @@ A constant to avoid writing the `astro:after-swap` event name in plain text when

+:::caution[Scheduled for deprecation] +This constant is scheduled for deprecation in v6. You can still use it in your project, but you may prefer to update your code now. +::: + A constant to avoid writing the `astro:page-load` event name in plain text when you define an event. ```astro title="src/pages/index.astro" "TRANSITION_PAGE_LOAD"