Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document ViewTransitions API reference #9174

Merged
merged 18 commits into from
Aug 29, 2024
Merged

Document ViewTransitions API reference #9174

Changes from 3 commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
650508b
Start documenting the VT API reference
Fryuni Aug 23, 2024
d0e6eff
Document more VT client APIs
Fryuni Aug 23, 2024
7a48687
Document View Transition Events
Fryuni Aug 24, 2024
7eb8270
Apply suggestions from Armand code review
sarah11918 Aug 28, 2024
d4f21e1
Merge branch 'main' into fryuni/view-transition-events
sarah11918 Aug 28, 2024
536bdb3
Apply suggestions from Armand code review
sarah11918 Aug 28, 2024
3ad7338
Merge branch 'main' into fryuni/view-transition-events
sarah11918 Aug 29, 2024
1f960d4
Apply suggestions from code review
Fryuni Aug 29, 2024
9f4b672
Merge branch 'main' into fryuni/view-transition-events
sarah11918 Aug 29, 2024
ebc61a2
happy path...
sarah11918 Aug 29, 2024
9549d50
Apply suggestions from Yan code review
sarah11918 Aug 29, 2024
a85c605
more yan
sarah11918 Aug 29, 2024
f383129
sarah formatting
sarah11918 Aug 29, 2024
2454ee0
earlier change not applied?
sarah11918 Aug 29, 2024
de47b05
Sarah proofreading/editing
sarah11918 Aug 29, 2024
c817614
Merge branch 'main' into fryuni/view-transition-events
sarah11918 Aug 29, 2024
18d6eeb
Remove incorrect field from events
Fryuni Aug 29, 2024
1fd61d0
Merge branch 'main' into fryuni/view-transition-events
Fryuni Aug 29, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
336 changes: 336 additions & 0 deletions src/content/docs/en/reference/api-reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2075,6 +2075,342 @@
})
```

## View Transitions client API (`astro:transitions/client`)

<p><Since v="3.2.0" /></p>

This module provides functions to control and interact with the View Transitions and client-side router.
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

For features and usage examples, [see our View Transitions guide](/en/guides/view-transitions/).

### `navigate()`

<p><Since v="3.2.0" /></p>

<p>
**Type:** `(href: string, options?: Options) => void`
</p>
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

Start a navigation to the given `href` using View Transitions.
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

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.

#### `history` option

<p><Since v="3.2.0" /></p>

<p>
**Type:** `'auto' | 'push' | 'replace'`
</p>
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

Defines how this navigation should be added to the browser history.

- `'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.
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

This option is follows the [`history` option](https://developer.mozilla.org/en-US/docs/Web/API/Navigation/navigate#history) from the browser Navigation API, but simplified for the cases that can happen on an Astro project.
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

#### `formData` option

<p><Since v="3.5.0" /></p>

<p>
**Type:** `FormData`
</p>
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

A `FormData` object for `POST` requests.

When this option is given, the requests to the navigation target page will be sent as a `POST` request with the given form data object as the content.
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

Submiting an HTML form with View Transitions enable will use this method in place of the default navigation with page reload. Calling this method allows triggering the same behavior programatically.
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

#### `info` option

<p><Since v="3.6.0" /></p>

<p>
**Type:** `any`
</p>
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

Arbitrary data to be included in the `astro:before-preparation` and `astro:before-swap` event caused by this navigation.
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

This option mimics the [`info` option](https://developer.mozilla.org/en-US/docs/Web/API/Navigation/navigate#info) from the browser Navigation API.

#### `state` option

<p><Since v="3.6.0" /></p>

<p>
**Type:** `any`
</p>
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

Arbitrary data to be associated with the `NavitationHistoryEntry` object created by this navigation. This data can then be retrieved using the [`history.getState` function](https://developer.mozilla.org/en-US/docs/Web/API/NavigationHistoryEntry/getState) from the History API.

This option mimics the [`state` option](https://developer.mozilla.org/en-US/docs/Web/API/Navigation/navigate#state) from the browser Navigation API.

#### `sourceElement` option

<p><Since v="3.6.0" /></p>

<p>
**Type:** `Element`
</p>
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

The element that triggered this navigation, if any. This element will be available in the following events:
- `astro:before-preparation`
- `astro:before-swap`

### `supportsViewTransitions`

<p><Since v="3.2.0" /></p>

<p>
**Type:** `boolean`
</p>
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

A constant that indicates whether View Transitions are supported and enabled in the current browser.
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

### `transitionEnabledOnThisPage`

<p><Since v="3.2.0" /></p>

<p>
**Type:** `boolean`
</p>
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

Whether the current page has the View Transitions enabled for client-side navigation. This can be used to make reusable components that adapt to when they are used on pages with and without View Transitions.
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

### `getFallback`

<p><Since v="3.6.0" /></p>

<p>
**Type:** `() => 'none' | 'animate' | 'swap'`
</p>
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

Returns the fallback strategy for View Transitions.
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

See the guide on [Fallback control](https://docs.astro.build/en/guides/view-transitions/#fallback-control) for how to chose and configure the fallback behavior.

Check failure on line 2194 in src/content/docs/en/reference/api-reference.mdx

View workflow job for this annotation

GitHub Actions / Check Links 

Unwanted absolute link in src/content/docs/en/reference/api-reference.mdx, line 2194: https://docs.astro.build/en/guides/view-transitions/#fallback-control Suggested fix: /en/guides/view-transitions/#fallback-control
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

## View Transition Events

<p><Since v="3.6.0" /></p>
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

### `astro:before-preparation` event

An event dispatched at the beginning of a navigation using View Transitions. This event happens before any request is made and any browser state is changed.

This event has the attributes:
- [`info`](#info)
- [`state`](#state)

Check failure on line 2206 in src/content/docs/en/reference/api-reference.mdx

View workflow job for this annotation

GitHub Actions / Check Links 

Broken fragment link in src/content/docs/en/reference/api-reference.mdx, line 2206: The linked page does not contain a fragment with the name "#state". Available fragments: #theme-icons, #gradient, #starlight__sidebar, #starlight__mobile-toc, #starlight__on-this-page--mobile, #starlight__on-this-page, #_top, #astro-global, #astroglob, #markdown-files, #astro-files, #other-files, #astroprops, #astroparams, #astrorequest, #astroresponse, #astrocookies, #get, #has, #set, #delete, #merge, #headers, #astrocookie, #value, #json, #number, #boolean, #astrocookiegetoptions, #decode, #astrocookiesetoptions, #domain, #expires, #httponly, #maxage, #path, #samesite, #secure, #encode, #astroredirect, #astrorewrite, #astrourl, #astroclientaddress, #astrosite, #astrogenerator, #astroslots, #astroslotshas, #astroslotsrender, #astroself, #astrolocals, #astropreferredlocale, #astropreferredlocalelist, #astrocurrentlocale, #endpoint-context, #contextparams, #contextprops, #contextrequest, #contextcookies, #contexturl, #contextclientaddress, #contextsite, #contextgenerator, #contextredirect, #contextrewrite, #contextlocals, #getstaticpaths, #params, #data-passing-with-props, #paginate, #the-pagination-page-prop, #pagedata, #pagestart, #pageend, #pagesize, #pagetotal, #pagecurrentpage, #pagelastpage, #pageurlcurrent, #pageurlprev, #pageurlnext, #pageurlfirst, #pageurllast, #importmeta, #images-astroassets, #getimage, #content-collections-astrocontent, #definecollection, #type, #schema, #reference, #getcollection, #getentry, #getentries, #getentrybyslug, #getdataentrybyid, #collection-entry-type, #id, #collection, #data, #slug, #body, #render, #other-content-collection-types, #collectionkey, #contentcollectionkey, #datacollectionkey, #schemacontext, #middleware-astromiddleware, #onrequest, #context, #next, #sequence, #createcontext, #tryserializelocals, #internationalization-astroi18n, #getrelativelocaleurl, #getabsolutelocaleurl, #getrelativelocaleurllist, #getabsolutelocaleurllist, #getpathbylocale, #getlocalebypath, #redirecttodefaultlocale, #redirecttofallback, #notfound, #middleware, #requesthaslocale, #view-transitions-client-api-astrotransitionsclient, #navigate, #history-option, #formdata-option, #info-option, #state-option, #sourceelement-option, #supportsviewtransitions, #transitionenabledonthispage, #getfallback, #view-transition-events, #astrobefore-preparation-event, #astroafter-preparation, #astrobefore-swap, #astroafter-swap, #astropage-load, #view-transitions-events-attributes, #info, #sourceelement, #newdocument, #navigationtype, #direction, #from, #to, #formdata, #loader, #viewtransition, #swap, #deselectscripts, #swaprootattributes, #swapheadelements, #savefocus, #swapbodyelements, #built-in-components, #code-, #transformers, #fragment-, #prism-, #tab-590, #tab-591, #tab-592, #tab-panel-590, #tab-panel-591, #tab-panel-592, #image-, #properties, #picture-, #properties-1, #formats, #fallbackformat, #pictureattributes, #content-, #viewtransitions-, #debug-, #docsearch-lvl0, #issue140jeiz, #idea140jeiz, #other140jeiz, #textarea140jeiz
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved
- [`sourceElement`](#sourcelement)

Check failure on line 2207 in src/content/docs/en/reference/api-reference.mdx

View workflow job for this annotation

GitHub Actions / Check Links 

Broken fragment link in src/content/docs/en/reference/api-reference.mdx, line 2207: The linked page does not contain a fragment with the name "#sourcelement". Available fragments: #theme-icons, #gradient, #starlight__sidebar, #starlight__mobile-toc, #starlight__on-this-page--mobile, #starlight__on-this-page, #_top, #astro-global, #astroglob, #markdown-files, #astro-files, #other-files, #astroprops, #astroparams, #astrorequest, #astroresponse, #astrocookies, #get, #has, #set, #delete, #merge, #headers, #astrocookie, #value, #json, #number, #boolean, #astrocookiegetoptions, #decode, #astrocookiesetoptions, #domain, #expires, #httponly, #maxage, #path, #samesite, #secure, #encode, #astroredirect, #astrorewrite, #astrourl, #astroclientaddress, #astrosite, #astrogenerator, #astroslots, #astroslotshas, #astroslotsrender, #astroself, #astrolocals, #astropreferredlocale, #astropreferredlocalelist, #astrocurrentlocale, #endpoint-context, #contextparams, #contextprops, #contextrequest, #contextcookies, #contexturl, #contextclientaddress, #contextsite, #contextgenerator, #contextredirect, #contextrewrite, #contextlocals, #getstaticpaths, #params, #data-passing-with-props, #paginate, #the-pagination-page-prop, #pagedata, #pagestart, #pageend, #pagesize, #pagetotal, #pagecurrentpage, #pagelastpage, #pageurlcurrent, #pageurlprev, #pageurlnext, #pageurlfirst, #pageurllast, #importmeta, #images-astroassets, #getimage, #content-collections-astrocontent, #definecollection, #type, #schema, #reference, #getcollection, #getentry, #getentries, #getentrybyslug, #getdataentrybyid, #collection-entry-type, #id, #collection, #data, #slug, #body, #render, #other-content-collection-types, #collectionkey, #contentcollectionkey, #datacollectionkey, #schemacontext, #middleware-astromiddleware, #onrequest, #context, #next, #sequence, #createcontext, #tryserializelocals, #internationalization-astroi18n, #getrelativelocaleurl, #getabsolutelocaleurl, #getrelativelocaleurllist, #getabsolutelocaleurllist, #getpathbylocale, #getlocalebypath, #redirecttodefaultlocale, #redirecttofallback, #notfound, #middleware, #requesthaslocale, #view-transitions-client-api-astrotransitionsclient, #navigate, #history-option, #formdata-option, #info-option, #state-option, #sourceelement-option, #supportsviewtransitions, #transitionenabledonthispage, #getfallback, #view-transition-events, #astrobefore-preparation-event, #astroafter-preparation, #astrobefore-swap, #astroafter-swap, #astropage-load, #view-transitions-events-attributes, #info, #sourceelement, #newdocument, #navigationtype, #direction, #from, #to, #formdata, #loader, #viewtransition, #swap, #deselectscripts, #swaprootattributes, #swapheadelements, #savefocus, #swapbodyelements, #built-in-components, #code-, #transformers, #fragment-, #prism-, #tab-590, #tab-591, #tab-592, #tab-panel-590, #tab-panel-591, #tab-panel-592, #image-, #properties, #picture-, #properties-1, #formats, #fallbackformat, #pictureattributes, #content-, #viewtransitions-, #debug-, #docsearch-lvl0, #issue140jeiz, #idea140jeiz, #other140jeiz, #textarea140jeiz
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved
- [`navigationType`](#navigationtype)
- [`direction`](#direction)
- [`from`](#from)
- [`to`](#to)
- [`formData`](#formdata)
- [`loader`](#loader)

Read more about how to use this event on the [View Transitions guide](/en/guides/view-transitions/#astrobefore-preparation).

### `astro:after-preparation`
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

An event dispatched after the next page in a navigation using View Transitions is loaded.

This event has no attributes.

Read more about how to use this event on the [View Transitions guide](/en/guides/view-transitions/#astroafter-preparation).

### `astro:before-swap`
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

An event dispatched after the next page is parsed and prepared and linked into a document in preparation for the transition but before any content is swapped between the documents.
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

This event can't be canceled. Calling `preventDefault()` is a no-op.

This event has the attributes:
- [`info`](#info)
- [`state`](#state)

Check failure on line 2233 in src/content/docs/en/reference/api-reference.mdx

View workflow job for this annotation

GitHub Actions / Check Links 

Broken fragment link in src/content/docs/en/reference/api-reference.mdx, line 2233: The linked page does not contain a fragment with the name "#state". Available fragments: #theme-icons, #gradient, #starlight__sidebar, #starlight__mobile-toc, #starlight__on-this-page--mobile, #starlight__on-this-page, #_top, #astro-global, #astroglob, #markdown-files, #astro-files, #other-files, #astroprops, #astroparams, #astrorequest, #astroresponse, #astrocookies, #get, #has, #set, #delete, #merge, #headers, #astrocookie, #value, #json, #number, #boolean, #astrocookiegetoptions, #decode, #astrocookiesetoptions, #domain, #expires, #httponly, #maxage, #path, #samesite, #secure, #encode, #astroredirect, #astrorewrite, #astrourl, #astroclientaddress, #astrosite, #astrogenerator, #astroslots, #astroslotshas, #astroslotsrender, #astroself, #astrolocals, #astropreferredlocale, #astropreferredlocalelist, #astrocurrentlocale, #endpoint-context, #contextparams, #contextprops, #contextrequest, #contextcookies, #contexturl, #contextclientaddress, #contextsite, #contextgenerator, #contextredirect, #contextrewrite, #contextlocals, #getstaticpaths, #params, #data-passing-with-props, #paginate, #the-pagination-page-prop, #pagedata, #pagestart, #pageend, #pagesize, #pagetotal, #pagecurrentpage, #pagelastpage, #pageurlcurrent, #pageurlprev, #pageurlnext, #pageurlfirst, #pageurllast, #importmeta, #images-astroassets, #getimage, #content-collections-astrocontent, #definecollection, #type, #schema, #reference, #getcollection, #getentry, #getentries, #getentrybyslug, #getdataentrybyid, #collection-entry-type, #id, #collection, #data, #slug, #body, #render, #other-content-collection-types, #collectionkey, #contentcollectionkey, #datacollectionkey, #schemacontext, #middleware-astromiddleware, #onrequest, #context, #next, #sequence, #createcontext, #tryserializelocals, #internationalization-astroi18n, #getrelativelocaleurl, #getabsolutelocaleurl, #getrelativelocaleurllist, #getabsolutelocaleurllist, #getpathbylocale, #getlocalebypath, #redirecttodefaultlocale, #redirecttofallback, #notfound, #middleware, #requesthaslocale, #view-transitions-client-api-astrotransitionsclient, #navigate, #history-option, #formdata-option, #info-option, #state-option, #sourceelement-option, #supportsviewtransitions, #transitionenabledonthispage, #getfallback, #view-transition-events, #astrobefore-preparation-event, #astroafter-preparation, #astrobefore-swap, #astroafter-swap, #astropage-load, #view-transitions-events-attributes, #info, #sourceelement, #newdocument, #navigationtype, #direction, #from, #to, #formdata, #loader, #viewtransition, #swap, #deselectscripts, #swaprootattributes, #swapheadelements, #savefocus, #swapbodyelements, #built-in-components, #code-, #transformers, #fragment-, #prism-, #tab-590, #tab-591, #tab-592, #tab-panel-590, #tab-panel-591, #tab-panel-592, #image-, #properties, #picture-, #properties-1, #formats, #fallbackformat, #pictureattributes, #content-, #viewtransitions-, #debug-, #docsearch-lvl0, #issue140jeiz, #idea140jeiz, #other140jeiz, #textarea140jeiz
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved
- [`sourceElement`](#sourcelement)

Check failure on line 2234 in src/content/docs/en/reference/api-reference.mdx

View workflow job for this annotation

GitHub Actions / Check Links 

Broken fragment link in src/content/docs/en/reference/api-reference.mdx, line 2234: The linked page does not contain a fragment with the name "#sourcelement". Available fragments: #theme-icons, #gradient, #starlight__sidebar, #starlight__mobile-toc, #starlight__on-this-page--mobile, #starlight__on-this-page, #_top, #astro-global, #astroglob, #markdown-files, #astro-files, #other-files, #astroprops, #astroparams, #astrorequest, #astroresponse, #astrocookies, #get, #has, #set, #delete, #merge, #headers, #astrocookie, #value, #json, #number, #boolean, #astrocookiegetoptions, #decode, #astrocookiesetoptions, #domain, #expires, #httponly, #maxage, #path, #samesite, #secure, #encode, #astroredirect, #astrorewrite, #astrourl, #astroclientaddress, #astrosite, #astrogenerator, #astroslots, #astroslotshas, #astroslotsrender, #astroself, #astrolocals, #astropreferredlocale, #astropreferredlocalelist, #astrocurrentlocale, #endpoint-context, #contextparams, #contextprops, #contextrequest, #contextcookies, #contexturl, #contextclientaddress, #contextsite, #contextgenerator, #contextredirect, #contextrewrite, #contextlocals, #getstaticpaths, #params, #data-passing-with-props, #paginate, #the-pagination-page-prop, #pagedata, #pagestart, #pageend, #pagesize, #pagetotal, #pagecurrentpage, #pagelastpage, #pageurlcurrent, #pageurlprev, #pageurlnext, #pageurlfirst, #pageurllast, #importmeta, #images-astroassets, #getimage, #content-collections-astrocontent, #definecollection, #type, #schema, #reference, #getcollection, #getentry, #getentries, #getentrybyslug, #getdataentrybyid, #collection-entry-type, #id, #collection, #data, #slug, #body, #render, #other-content-collection-types, #collectionkey, #contentcollectionkey, #datacollectionkey, #schemacontext, #middleware-astromiddleware, #onrequest, #context, #next, #sequence, #createcontext, #tryserializelocals, #internationalization-astroi18n, #getrelativelocaleurl, #getabsolutelocaleurl, #getrelativelocaleurllist, #getabsolutelocaleurllist, #getpathbylocale, #getlocalebypath, #redirecttodefaultlocale, #redirecttofallback, #notfound, #middleware, #requesthaslocale, #view-transitions-client-api-astrotransitionsclient, #navigate, #history-option, #formdata-option, #info-option, #state-option, #sourceelement-option, #supportsviewtransitions, #transitionenabledonthispage, #getfallback, #view-transition-events, #astrobefore-preparation-event, #astroafter-preparation, #astrobefore-swap, #astroafter-swap, #astropage-load, #view-transitions-events-attributes, #info, #sourceelement, #newdocument, #navigationtype, #direction, #from, #to, #formdata, #loader, #viewtransition, #swap, #deselectscripts, #swaprootattributes, #swapheadelements, #savefocus, #swapbodyelements, #built-in-components, #code-, #transformers, #fragment-, #prism-, #tab-590, #tab-591, #tab-592, #tab-panel-590, #tab-panel-591, #tab-panel-592, #image-, #properties, #picture-, #properties-1, #formats, #fallbackformat, #pictureattributes, #content-, #viewtransitions-, #debug-, #docsearch-lvl0, #issue140jeiz, #idea140jeiz, #other140jeiz, #textarea140jeiz
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved
- [`navigationType`](#navigationtype)
- [`direction`](#direction)
- [`from`](#from)
- [`to`](#to)
- [`viewTransition`](#viewtransition)
- [`swap`](#swap)

Read more about how to use this event on the [View Transitions guide](/en/guides/view-transitions/#astrobefore-swap).

### `astro:after-swap`
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

An event dispatched after the contents of the page have been swapped but before the view transition ends.

The history entry has already been updated when this event is triggered.
Fryuni marked this conversation as resolved.
Show resolved Hide resolved

### `astro:page-load`
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

An event dispatched after a page completes loading, be it from a navigation using View Transition or native to the browser.

When view transitions is enabled in the page, code that would normally execute on `DOMContentLoaded` should be changed to execute on this event.

### View Transitions events attributes

<p><Since v="3.6.0" /></p>

#### `info`

<p>
*Type:* `URL`
</p>
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

Arbitrary data defined during navigation.

This is the literal value passed on the [`info` option](#info-option) of the [`navigate()` function](#navigate).

#### `sourceElement`

<p>
*Type:* `Element | undefined`
</p>
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

The element that triggered the navigation. This can be, for example, an `<a>` element that was clicked.

When using the [`navigate()` function](#navigate), this will be the element specified in the call.

#### `newDocument`

<p>
*Type:* `Document`
</p>
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

The document for the next page in the navigation. The contents of this document will be swapped in place of the contents of the current document.

#### `navigationType`

<p>
*Type:* `'push' | 'replace' | 'traverse'`
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved
</p>

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)

#### `direction`

<p>
*Type:* `Direction`
</p>
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

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.

#### `from`

<p>
*Type:* `URL`
</p>
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

The URL of the page initiating the navigation.

#### `to`

<p>
*Type:* `URL`
</p>
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

The URL of the page being navigated to. This property can be modified, the value at the end of the lifecycle will be used in the `NavigationHistoryEntry` for the next page.

#### `formData`

<p>
*Type:* `FormData | undefined`
</p>
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

A `FormData` object for `POST` requests.

When this attribute is set, a `POST` requests will be sent to the [`to` URL](#to) with the given form data object as the content instead of the normal `GET` request.
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

When submiting 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.
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

#### `loader`

<p>
*Type:* `() => Promise<void>`
</p>
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

Implementation of the following phase in the navigation (loading the next page). This implementation can be overriden to add extra behavior or to prevent the execution of the next phase.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

... or to prevent the execution of the next phase

That is a mystery to me. Do we have any examples of this anywhere? Why would you do that? And why does it cancel the next phase? Calling preventDefault() for the astro:before-preparation event, on the other hand, is fine.

If we do not persuade users of this, we do not need to warn them in the following

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I haven't seen an example, nor can I think of any particular use case where you'd want to override this and not call the original at some point in the new function, but technically, you can.

I'm fine with not mentioning it on the docs tho.


:::caution
Overriding this implementation to prevent the execution may leave the browser on an inconsistent navigation state. It is normally preferred to use `preventDefault()` if you just want to cancel the navigation and stay in the current page.
:::
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

#### `viewTransition`

<p>
*Type:* [`ViewTransition`](https://developer.mozilla.org/en-US/docs/Web/API/ViewTransition)
</p>
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

The view transition object used in this navigation. On browser 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.
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

#### `swap`

<p>
*Type:* `() => void`
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved
</p>

Implementation of the document swap logic.

Read more on how to how to [build your own custom swap function](/en/guides/view-transitions/#building-a-custom-swap-function) on the View Transitions guide.

Check failure on line 2367 in src/content/docs/en/reference/api-reference.mdx

View workflow job for this annotation

GitHub Actions / Check Links 

Broken fragment link in src/content/docs/en/reference/api-reference.mdx, line 2367: The linked page does not contain a fragment with the name "#building-a-custom-swap-function". Available fragments: #theme-icons, #gradient, #starlight__sidebar, #starlight__mobile-toc, #starlight__on-this-page--mobile, #starlight__on-this-page, #_top, #adding-view-transitions-to-a-page, #full-site-view-transitions-spa-mode, #transition-directives, #naming-a-transition, #maintaining-state, #transitionpersist-props, #built-in-animation-directives, #customizing-animations, #router-control, #preventing-client-side-navigation, #trigger-navigation, #replace-entries-in-the-browser-history, #transitions-with-forms, #fallback-control, #client-side-navigation-process, #script-behavior-with-view-transitions, #script-order, #script-re-execution, #data-astro-rerun, #lifecycle-events, #astrobefore-preparation, #astroafter-preparation, #astrobefore-swap, #astroafter-swap, #astropage-load, #accessibility, #route-announcement, #prefers-reduced-motion, #docsearch-lvl0, #issue37oj7wz, #idea37oj7wz, #other37oj7wz, #textarea37oj7wz
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

By default this implementation will call the following functions in order:
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

##### `deselectScripts()`

<p>
*Type:* `(newDocument: Document) => void`
</p>
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

Marks scripts in the new document that should not be executed. Those scripts are already in the current document and are not flagged for re-execution using [`data-astro-rerun`](/en/guides/view-transitions/#data-astro-rerun).

##### `swapRootAttributes()`

<p>
*Type:* `(newDocument: Document) => void`
</p>
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

Swaps the Astro-injected internal attributes between the document roots, like the document scope hash.
Fryuni marked this conversation as resolved.
Show resolved Hide resolved

When making a custom swap function, it is important to call this function. Such attributes are used for Client Islands hydration and CSS scoping.
Fryuni marked this conversation as resolved.
Show resolved Hide resolved

##### `swapHeadElements()`

<p>
*Type:* `(newDocument: Document) => void`
</p>
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

Removes every element from the current document's `<head>` that is not persisted to the new document. Then appends all new elements from the new document's `<head>` to the current document's `<head>`.

##### `saveFocus()`

<p>
*Type:* `() => () => void`
</p>
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

Stores the element in focus on the current page and returns a function that when called, if the focused element was persisted, returns the focus to it.


##### `swapBodyElements()`

<p>
*Type:* `(newBody: Element, oldBody: Element) => void`
</p>
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

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.

## Built-in Components

Astro includes several built-in components for you to use in your projects. All built-in components are available in `.astro` files via `import {} from 'astro:components';`.
Expand Down
Loading