diff --git a/src/content/docs/en/guides/upgrade-to/v3.mdx b/src/content/docs/en/guides/upgrade-to/v3.mdx
index e9d500e69f554..2235ef259a995 100644
--- a/src/content/docs/en/guides/upgrade-to/v3.mdx
+++ b/src/content/docs/en/guides/upgrade-to/v3.mdx
@@ -63,7 +63,7 @@ export default defineConfig({
These features are now available by default:
-- [View Transitions](/en/guides/view-transitions/) for animated page transitions and persistent islands.
+- View Transitions for animated page transitions and persistent islands. See [view transitions API breaking changes and upgrading advice](/en/guides/view-transitions/#upgrade-to-v30-from-v2x) if you were using this experimental flag.
- A new image services API `astro:assets` for using images in Astro, including a new `` component and `getImage()` function. Please read the detailed [image upgrade advice](/en/guides/images/#upgrade-to-v30-from-v2x) **whether or not you were using this experimental flag** to see how this might affect your project.
Read more about these two exciting features and more in the 3.0 Blog post!
diff --git a/src/content/docs/en/guides/view-transitions.mdx b/src/content/docs/en/guides/view-transitions.mdx
index e70eb38d63f71..81193b5cc1b92 100644
--- a/src/content/docs/en/guides/view-transitions.mdx
+++ b/src/content/docs/en/guides/view-transitions.mdx
@@ -1,52 +1,56 @@
---
-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 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](#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).
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 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).
-:::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
+:::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.
+:::
-You can enable support for animated page transitions through the experimental `viewTransitions` flag in your Astro config:
+## Adding View Transitions to a Page
-```js title="astro.config.mjs" ins={4-6}
-import { defineConfig } from 'astro/config';
+Opt in to using view transitions on individual pages by importing and adding the `` routing component to `` on every desired page.
-export default defineConfig({
- experimental: {
- viewTransitions: true
- }
-});
+```astro title="src/pages/index.astro" ins={2,7}
+---
+import { ViewTransitions } from 'astro:transitions';
+---
+
+
+ My Homepage
+
+
+
+
Welcome to my website!
+
+
```
-:::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.
+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.
@@ -88,9 +94,9 @@ In some cases, you may want or need to identify the corresponding view transitio