withastro · matthewp · Jul 19, 2023 · Jun 28, 2023 · Jun 28, 2023 · Jun 28, 2023
diff --git a/.changeset/silly-garlics-live.md b/.changeset/silly-garlics-live.md
@@ -0,0 +1,60 @@
+---
+'astro': minor
+---
+
+Built-in View Transitions Support (experimental)
+
+Astro now supports [view transitions](https://developer.chrome.com/docs/web-platform/view-transitions/) through the new `<ViewTransitions />` component and the `transition:animate` (and associated) directives. View transitions are a great fit for content-oriented sites, and we see it as the best path to get the benefits of client-side routing (smoother transitions) without sacrificing the more simple mental model of MPAs.
+
+In this release, view transitions are enabled by add the experimental flag to your config:
+
+```js
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+  experimental: {
+    viewTransitions: true,
+  },
+})
+```
+
+This enables you to use the new APIs added.
+
+## <ViewTransitions />
+
+This is a component which acts as the *router* for transitions between pages. You need to add it to each page, in the `<head>` section, in which you want to have transitions away from be done in-client. To enable support throughout your entire app, add the component in some common layout or component.
+
+__CommonHead.astro__
+
+```astro
+---
+import { ViewTransitions } from 'astro:transitions';
+---
+
+<meta charset="utf-8">
+<title>{Astro.props.title}</title>
+<ViewTransitions />
+```
+
+With only this change, your app will now route completely in-client. You can then add transitions to individual elements using the `transition:animate` directive.
+
+## Animations
+
+Using `transition:animate` you can use some of our built-in animations. For example:
+
+```astro
+<header transition:animate="slide">
+```
+
+Will perform an animation in which the element slides out to the left, and slides in from the right. You can also customize these animations by specifying a duration like so:
+
+```astro
+---
+import { slide } from 'astro:transition';
+---
+<header transition:animate={slide({ duration: 200 })}>
+```
+
+## Continue learning
+
+Checkout the [docs](https://docs.astro.build/en/guides/client-side-routing/) to learn more.
diff --git a/examples/basics/astro.config.mjs b/examples/basics/astro.config.mjs
@@ -1,4 +1,8 @@
 import { defineConfig } from 'astro/config';
 
 // https://astro.build/config
-export default defineConfig({});
+export default defineConfig({
+	experimental: {
+		viewTransitions: true,
+	},
+});
diff --git a/examples/basics/src/layouts/Layout.astro b/examples/basics/src/layouts/Layout.astro
@@ -1,4 +1,6 @@
 ---
+import { ViewTransitions } from 'astro:transitions';
+
 interface Props {
 	title: string;
 }
@@ -15,8 +17,9 @@ const { title } = Astro.props;
 		<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
 		<meta name="generator" content={Astro.generator} />
 		<title>{title}</title>
+		<ViewTransitions />
 	</head>
-	<body>
+	<body transition:animate="fade">
 		<slot />
 	</body>
 </html>

diff --git a/examples/blog/astro.config.mjs b/examples/blog/astro.config.mjs
@@ -7,4 +7,7 @@ import sitemap from '@astrojs/sitemap';
 export default defineConfig({
 	site: 'https://example.com',
 	integrations: [mdx(), sitemap()],
+	experimental: {
+		viewTransitions: true,
+	}
 });
diff --git a/examples/blog/src/components/BaseHead.astro b/examples/blog/src/components/BaseHead.astro
@@ -2,6 +2,7 @@
 // Import the global.css file here so that it is included on
 // all pages through the use of the <BaseHead /> component.
 import '../styles/global.css';
+import { ViewTransitions } from 'astro:transitions';
 
 interface Props {
 	title: string;
@@ -41,3 +42,4 @@ const { title, description, image = '/placeholder-social.jpg' } = Astro.props;
 <meta property="twitter:title" content={title} />
 <meta property="twitter:description" content={description} />
 <meta property="twitter:image" content={new URL(image, Astro.url)} />
+<ViewTransitions />
diff --git a/examples/blog/src/components/Header.astro b/examples/blog/src/components/Header.astro
@@ -3,7 +3,7 @@ import HeaderLink from './HeaderLink.astro';
 import { SITE_TITLE } from '../consts';
 ---
 
-<header>
+<header transition:animate="morph">
 	<h2>
 		{SITE_TITLE}
 	</h2>

diff --git a/examples/blog/src/layouts/BlogPost.astro b/examples/blog/src/layouts/BlogPost.astro
@@ -27,8 +27,7 @@ const { title, description, pubDate, updatedDate, heroImage } = Astro.props;
 			}
 		</style>
 	</head>
-
-	<body>
+	<body transition:animate="slide">
 		<Header />
 		<main>
 			<article>

diff --git a/examples/blog/src/pages/blog/index.astro b/examples/blog/src/pages/blog/index.astro
@@ -33,7 +33,7 @@ const posts = (await getCollection('blog')).sort(
 			}
 		</style>
 	</head>
-	<body>
+	<body transition:animate="slide">
 		<Header />
 		<main>
 			<section>

diff --git a/examples/blog/src/pages/index.astro b/examples/blog/src/pages/index.astro
@@ -10,7 +10,7 @@ import { SITE_TITLE, SITE_DESCRIPTION } from '../consts';
 	<head>
 		<BaseHead title={SITE_TITLE} description={SITE_DESCRIPTION} />
 	</head>
-	<body>
+	<body transition:animate="slide">
 		<Header title={SITE_TITLE} />
 		<main>
 			<h1>🧑‍🚀 Hello, Astronaut!</h1>

diff --git a/examples/hackernews/astro.config.mjs b/examples/hackernews/astro.config.mjs
@@ -7,4 +7,7 @@ export default defineConfig({
 	adapter: node({
 		mode: 'standalone',
 	}),
+	experimental: {
+		viewTransitions: true,
+	},
 });
diff --git a/examples/hackernews/src/layouts/Layout.astro b/examples/hackernews/src/layouts/Layout.astro
@@ -1,4 +1,5 @@
 ---
+import { ViewTransitions } from 'astro:transitions';
 import Nav from '../components/Nav.astro';
 ---
 
@@ -10,8 +11,9 @@ import Nav from '../components/Nav.astro';
 		<meta name="generator" content={Astro.generator} />
 		<title>Astro - Hacker News</title>
 		<meta name="description" content="Hacker News Clone built with Astro" />
+		<ViewTransitions />
 	</head>
-	<body>
+	<body transition:animate="fade">
 		<Nav />
 		<slot />
 		<style is:global>

diff --git a/examples/portfolio/astro.config.mjs b/examples/portfolio/astro.config.mjs
@@ -1,4 +1,8 @@
 import { defineConfig } from 'astro/config';
 
 // https://astro.build/config
-export default defineConfig({});
+export default defineConfig({
+	experimental: {
+		viewTransitions: true,
+	}
+});
diff --git a/examples/portfolio/src/components/MainHead.astro b/examples/portfolio/src/components/MainHead.astro
@@ -1,4 +1,5 @@
 ---
+import { ViewTransitions } from 'astro:transitions';
 import '../styles/global.css';
 
 interface Props {
@@ -25,7 +26,7 @@ const {
 	href="https://fonts.googleapis.com/css2?family=Public+Sans:ital,wght@0,400;0,700;1,400&family=Rubik:wght@500;600&display=swap"
 	rel="stylesheet"
 />
-
+<ViewTransitions />
 <script is:inline>
 	// This code is inlined in the head to make dark mode instant & blocking.
 	const getThemePreference = () => {

diff --git a/examples/portfolio/src/layouts/BaseLayout.astro b/examples/portfolio/src/layouts/BaseLayout.astro
@@ -19,7 +19,7 @@ const { title, description } = Astro.props;
 	<head>
 		<MainHead title={title} description={description} />
 	</head>
-	<body>
+	<body transition:animate="morph">
 		<div class="stack backgrounds">
 			<Nav />
 			<slot />

diff --git a/examples/with-tailwindcss/astro.config.mjs b/examples/with-tailwindcss/astro.config.mjs
@@ -5,4 +5,7 @@ import tailwind from '@astrojs/tailwind';
 // https://astro.build/config
 export default defineConfig({
 	integrations: [mdx(), tailwind()],
+	experimental: {
+		viewTransitions: true,
+	}
 });
diff --git a/examples/with-tailwindcss/src/layouts/main.astro b/examples/with-tailwindcss/src/layouts/main.astro
@@ -1,4 +1,5 @@
 ---
+import { ViewTransitions } from 'astro:transitions';
 const { content } = Astro.props;
 ---
 
@@ -8,8 +9,9 @@ const { content } = Astro.props;
 		<meta name="viewport" content="width=device-width" />
 		<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
 		<title>{content.title}</title>
+		<ViewTransitions />
 	</head>
-	<body>
+	<body transition:animate="morph">
 		<slot />
 	</body>
 </html>
diff --git a/examples/with-tailwindcss/src/pages/index.astro b/examples/with-tailwindcss/src/pages/index.astro
@@ -1,6 +1,7 @@
 ---
 // Component Imports
 import Button from '../components/Button.astro';
+import { ViewTransitions } from 'astro:transitions';
 
 // Full Astro Component Syntax:
 // https://docs.astro.build/core-concepts/astro-components/
@@ -13,9 +14,9 @@ import Button from '../components/Button.astro';
 		<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
 		<meta name="generator" content={Astro.generator} />
 		<title>Astro + TailwindCSS</title>
+		<ViewTransitions />
 	</head>
-
-	<body>
+	<body transition:animate="morph">
 		<div class="grid place-items-center h-screen content-center">
 			<Button>Tailwind Button in Astro!</Button>
 			<a href="/markdown-page" class="p-4 underline">Markdown is also supported...</a>

diff --git a/packages/astro/client-base.d.ts b/packages/astro/client-base.d.ts
@@ -70,6 +70,15 @@ declare module 'astro:assets' {
 	export const { getImage, getConfiguredImageService, Image }: AstroAssets;
 }
 
+declare module 'astro:transitions' {
+	type TransitionModule = typeof import('./dist/transitions/index.js');
+	export const slide: TransitionModule['slide'];
+	export const fade: TransitionModule['fade'];
+
+	type ViewTransitionsModule = typeof import('./components/ViewTransitions.astro');
+	export const ViewTransitions: ViewTransitionsModule['default'];
+}
+
 type MD = import('./dist/@types/astro').MarkdownInstance<Record<string, any>>;
 interface ExportedMarkdownModuleEntities {
 	frontmatter: MD['frontmatter'];