Skip to content
Bag of Tricks

Last updated: First published:

View Transitions for Starlight Sites

There are different ways to give your Starlight site a nice boost with view transitions. Your choice are mainly whether your want to go with Astro’s client router or with browser-native cross-document view transitions. This page gives you a quick overview so you can pick the path that fits you best.

Option 1: With Astro’s <ClientRouter />

Section titled “Option 1: With Astro’s <ClientRouter />”

The client router turns your Starlight site into a single page application. Your users enjoy smooth navigation without full page reloads.

This is the older approach from the time when browsers had no native support for cross-document view transitions.

Choose this option if you need shared state across navigation.

What you get

Section titled “What you get”
  • SPA navigation that eliminates full page loads
  • Works in all major browsers
  • Component state like search queries and results stay intact across navigation
  • May require extra steps to re-initialize third party scripts after navigation

What the Bag of Tricks adds

Section titled “What the Bag of Tricks adds”

To simplify the use of Astro’s client router, the Bag of Tricks offers a replacement for Starlight’s default <Head> component and a three step setup to get everything running. It also includes suggestions and options to help you extend and customize your setup including additional styling and loading indicators.

bot
˂ClientRouter /˃ View Transitions for Starlight Howto and components to use Astro's view transition support with Starlight

Option 2: Native View Transition API

Section titled “Option 2: Native View Transition API”

This approach keeps your site close to a classic multi page setup while still hiding full page load by leveraging browser’s native cross-document view transitions.

Choose this option if you prefer the framework agnostic web standard and can accept that Firefox might need a bit more time to catch up.

What you get

Section titled “What you get”
  • SPA-like navigation even with full page loads
  • Works in all major browsers except Firefox for now
  • Can’t share component state across navigation
  • Third party scripts behave as they did before

What the Bag of Tricks adds

Section titled “What the Bag of Tricks adds”

The Bag of Tricks provides a Starlight plugin that enables cross-document view transitions and enhances the experience. It adjusts navigation flow, main area behavior, and page titles, adds directional animations, and polishes the overall appearance.

vtbag
Native View Transitions for Starlight Let your site sparkle with this Starlight plugin for native view transitions

Bonus: Most Minimalistic Approach

Section titled “Bonus: Most Minimalistic Approach”

A very simple variant of Option 2.

You’re satisfied with the default cross-fade effect on navigation and can accept that the transitions would not yet show in Firefox? Then you can enable browser-native view transitions by simply adding the following lines to your custom.css↗ and you are all set.

@media (prefers-reduced-motion: no-preference) {
  @view-transition {
    navigation: auto;
  }
}