feat: ViewTransition Astro component

[abosch19]

What kind of changes does this PR include?

Allow user to set a new user configuration: viewTransitions (boolean)
This config sets Astro ViewTransitions component on Page layout if true

• Changes to Starlight code

Description

• What does this PR change? User configuration and Page layout

[changeset-bot]

⚠️ No Changeset found

Latest commit: 3718419

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[netlify]

✅ Deploy Preview for astro-starlight ready!

Name	Link
🔨 Latest commit	3718419
🔍 Latest deploy log	https://app.netlify.com/sites/astro-starlight/deploys/64fc6a516a047f0008947bda
😎 Deploy Preview	https://deploy-preview-694--astro-starlight.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 100 (no change from production) Accessibility: 100 (no change from production) Best Practices: 100 (no change from production) SEO: 100 (no change from production) PWA: - View the detailed breakdown and full score reports

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[turbek]

It looks like this currently breaks the pagefind/search functionality and also needs an astro version update. (checked on a forked version)

[delucis]

It looks like this currently breaks the pagefind/search functionality and also needs an astro version update.

Thanks for testing that @turbek! Yes, View Transitions require all client-side scripts to include special handling, so it may be more involved than the changes currently in this PR. We might be able to solve this with transition:persist, but I’m not sure — it could also require more complex updates to our scripts.

[turbek]

transition:persist="site-search" and a littlebit of extra code for the initialization solves the problem:

document.addEventListener('astro:page-load', () => {
	if (import.meta.env.DEV) return;

	const pageFind = document.querySelector('.pagefind-ui__search-input');

	if (pageFind) return;

	const onIdle = window.requestIdleCallback || ((cb) => setTimeout(cb, 1));
	onIdle(async () => {
		const { PagefindUI } = await import('@pagefind/default-ui');
		new PagefindUI({
			element: '#starlight__search',
			baseUrl: import.meta.env.BASE_URL,
			bundlePath: import.meta.env.BASE_URL.replace(/\/$/, '') + '/pagefind/',
			showImages: false,
			translations,
			showSubResults: true,
		});
	});
}, { once: true });

Although I'm not sure how ideal it is

[delucis]

Thanks for testing — I’d also assume other client-side scripts are impacted? Like table of contents highlighting and language/theme switching?

[turbek]

Actually we removed the language switching because we currently support 1 language and since our website doesn't support dark theme atm, we removed theme switching as well. So we never tested theme/language switching features with the SPA mode.

ToC highlighting seems to work as expected though.

[onemen]

I was able to activate View Transitions by overrides Starlight Head.astro component.

I omitted translations since i don't have any.

 npm install @pagefind/default-ui  

Add this custom Head.astro to your custom component in the components configuration option in astro.config.mjs:

---
import Default from '@starlight/components/Head.astro';
import type { Props } from '@starlight/props';
import { ViewTransitions } from 'astro:transitions';
---

<Default {...Astro.props}><slot /></Default>
<ViewTransitions />

<script>
  // Skip PagefindUI on initial page load since it's already run by Search.astro.

  // Flag to track initial page load
  let initialLoad = true;

  document.addEventListener('astro:page-load', () => {
    // Skip PagefindUI on initial page load (and only execute on subsequent loads)
    if (initialLoad) {
      initialLoad = false;
      return;
    }

    // Code to initialize PagefindUI on subsequent loads (if needed)
    if (import.meta.env.DEV) return;

    const pageFind = document.querySelector('.pagefind-ui__search-input');
    if (pageFind) return;

    const onIdle = window.requestIdleCallback || (cb => setTimeout(cb, 1));
    onIdle(async () => {
      // @ts-expect-error — Missing types for @pagefind/default-ui package.
      const { PagefindUI } = await import('@pagefind/default-ui');
      new PagefindUI({
        element: '#starlight__search',
        baseUrl: import.meta.env.BASE_URL,
        bundlePath: import.meta.env.BASE_URL.replace(/\/$/, '') + '/pagefind/',
        showImages: false,
        translations: {},
        showSubResults: true,
      });
    });
  });
</script>

[lukethacoder]

Super easy to add ViewTransitions to starlight in a similar way to @onemen, just needed to adjust the import paths.

Using @astrojs/starlight/* instead of @starlight/*

---
import Default from '@astrojs/starlight/components/Head.astro'
import type { Props } from '@astrojs/starlight/props'
import { ViewTransitions } from 'astro:transitions'
---

<Default {...Astro.props}><slot /></Default>
<ViewTransitions />

import { defineConfig } from 'astro/config'
import starlight from '@astrojs/starlight'

// https://astro.build/config
export default defineConfig({
  integrations: [
    starlight({
      components: {
        Head: './src/components/Head.astro',
      }
    }),
  ],
})

[Fryuni]

Adding VT to Starlight is quite simple, getting everything to behave correctly when VT is being used is the part that needs more work. Specifically:

• The theme switcher state gets reset
• The page theme gets mixed up
• Logo with light and dark variation appear doubled after a transition
• Search breaks / Depending on you fix it, the search is reinitialized on every transition and the old instance is not discarded (memory leak)
• The language switcher state gets weird (especially on 404 pages)

If your Starlight site is unaffected by those or if you think the compromise in those case is fine, then you can enable VT by adding the component to the head.

[martrapp]

Adding view transition to a starlight side might involve more than enabling the basic transitions.
Beside all the things Fryuni mentioned that must work if you use them, there is a brave new world of extensions you might want to have, once view transitions are enabled:

• Sidebar behavior that auto-opens categories if closed, e.g. on back navigation or that scrolls the current entry into view if it isn't
• Reasonable animations when you navigate after you scrolled a page down (this typically results in a large morph animations that looks like wild scrolling
• Animation direction dependent on the order of your pages

It might be possible to add all this and a lot of options to control that to starlight itself.
But this would also bring some complexity to the project.

For all being interested in a community solution for adding view transitions to starlight, have a look at the guide in the 👜 Bag of Tricks ✨:
https://events-3bg.pages.dev/jotter/starlight/guide/