Last updated: Dec 5, 2024First published: Jan 1, 1970

Guide: Add View Transitions to Starlight

This guide describes what has to be done to add view transitions to an existing Starlight site using the Starlight support of the 👜 Bag of Tricks ✨.

Starting from version 0.26.0, Starlight persists the state of the sidebar across navigation.

This already gives Starlight a lot of that SPA look and feel!

If you’re satisfied with having the view transition effect work only in Chromium-based browsers (such as Chrome, Edge, and Opera) and can do without it in Firefox, and other browsers that don’t yet support the cross-document features of the View Transition API, you can enable browser view transitions by simply adding the following line to your custom.css↗ and you are all set.

1
@view-transition {navigation: auto}

Otherwise stay tuned for how to add Astro’s <ViewTransitions> support to Starlight and enjoy view transitions on all browsers and thanks to Astro’s simulation even on Firefox and other browsers that do not yet have native support for the View Transition API.

Don’t be afraid that this will turn your beautiful website into a blinking jukebox. This Jotter is just an exaggerated example to show what is possible. If you follow the instructions below, you will be rewarded with a very subtle, SPA-like transition effect. And yes, if you want, you can of course later turn the whole thing into a … blinking jukebox.

The introduction page on The Bag’s view transition support for Starlight defines three categories of features for The Bag’s view transition support. This guide currently covers level 1, the mandatory features.

Enable View Transitions

To enable view transitions, you will extend Starlight’s Head component. You create a replacement component and instruct Starlight to use it as a substitute for its Head¹. The replacement component covers all aspects classified as mandatory actions. Components to cover the more optional things are in the works!

Step 1: Install astro-vtbot

The 👜 Bag of Tricks ✨ is available on npm. The package is named astro-vtbot. It can be installed as a package or as an Astro integration. See the installation page for details and differences. Let’s assume you just want to add it as a package:

1
cd /to/my/starlight/project
2
npm i -D astro-vtbot

Make sure that you have the latest version installed.

Step 2: Create a Head Component

Create a new component inside your project. The file name does not matter. For this example, we choose ./src/components/starlight/Head.astro. You can copy & paste the content for this file:

1
---
2
import type { Props } from '@astrojs/starlight/props';
3
import StarlightHead from '@astrojs/starlight/components/Head.astro';
4
import VtbotStarlight from 'astro-vtbot/components/starlight/Base.astro';
5
---
6

7
<VtbotStarlight {...Astro.props}>
8
  <StarlightHead {...Astro.props}><slot /></StarlightHead>
9
</VtbotStarlight>

Step 3: Use the New Head Component

Now you tell Starlight to replace its Head component with yours. Open the astro.config.mjs² file from your project directory. Make it look like shown below: Make sure that there is an entry named components in the options of your Starlight integration. It must specify a Head entry with the path of the file you have just created.

1
import { defineConfig } from 'astro/config';
2
import starlight from "@astrojs/starlight";
3

4
export default defineConfig({
5
  ...
6
  integrations: [starlight({
7
    ...
8
    components: {
9
      Head: "./src/components/starlight/Head.astro",
10
      ...
11
    },
12
    ...
13
  })]
14
})

You already had a different entry for Head: in your astro.config.mjs file?

In this case you have to change the import of StarlightHead in your new Head component. Change the import so that it does not load Starlight’s standard Head, but the component you had in your components mapping before:

1
---
2
// The file you had in you components mapping for Head before now goes here:
3
// You probably might have to change "./src" to "/src" to ensure the component is found
4
import StarlightHead from '@astrojs/starlight/components/Head.astro';
5
import StarlightHead from '/src/components/MySpecialHead.astro';
6
...

Try it out for yourself!

Start your project. No matter what browser you use, you should see that there are no full page loads when navigating. The scroll bar and category toggles do not reset when you go to the next page. The search bar remembers your last entry.

In Chromium browsers, you will see the browser’s standard animations for few transitions, i.e. a very quick fade-over of the complete viewport. Browser without native support for view transition will not yet show animations, but just seamlessly swap pages.

Having no fancy, whole viewport animation on a browser without native view transition support is a good thing here. As the exit and entry animations are required to play in sequence, you can not get a real cross-fade. But see here on how to add a cool animation to the main section.

In the next section, we will extend the view transition effect by adding an animation to the main content area and optimizing the styling.

Configuring View Transitions

You can configure several aspects of the view transition effect in your new Head component.

Animating the Main Section

You can add a transition:animate=... directive↗ to the <VtbotStarlight> component. The Bag will teleport the directive from there to the <main> element of the Starlight page. This is the way to enable view transition animations for the main content area of a Starlight site for all browsers.

1
<VtbotStarlight {...Astro.props} transition:animate="fade">
2
  <StarlightHead {...Astro.props}><slot /></StarlightHead>
3
</VtbotStarlight>

If you want to add further styling to the transition group, you can explicitly name it by accompanying transition:animate with transition:name="...". This way you replace the random name that Astro automatically gereted for you with a chosen name that you can use in CSS rules, see the extended configuration example below.

Fallback Control

What behavior↗ do you want for browsers that do not support view transitions natively? Choose from none, swap or animate. Use the viewTransitionFallback attribute of the <VtbotStarlight> component to tell The Bag what you have chosen:

1
<VtbotStarlight {...Astro.props} viewTransitionsFallback="animate">
2
  <StarlightHead {...Astro.props}><slot /></StarlightHead>
3
</VtbotStarlight>

This only serves as an example. It is not necessary to set viewTransitionsFallback to animate as this is the default setting anyway.

By the default, the sidebar content will not change on navigation. Only the current page marker will be changed, opened, and scrolled into view. There are several ways how you can change this behavior.

Additional Styling

You can also add a <style is:global> section to the file to style the ::view-transition-* pseudo elements for browsers with native view transition support.

Extended Configuration Example

Let’s revisit our Head component and see how it looks with the extensions described above:

1
---
2
import type { Props } from '@astrojs/starlight/props';
3
import StarlightHead from '@astrojs/starlight/components/Head.astro';
4
import VtbotStarlight from 'astro-vtbot/components/starlight/Base.astro';
5
import LoadingIndicator from 'astro-vtbot/components/LoadingIndicator.astro';
6
import ProgressBar from "astro-vtbot/components/ProgressBar.astro";
7

8
// import one of Astro's predefined animation functions,
9
// see https://docs.astro.build/en/guides/view-transitions/#built-in-animation-directives
10
import { slide } from 'astro:transitions';
11
---
12

13
{/* Define a view transition animation for `<main>`*/}
14
<VtbotStarlight
15
  {...Astro.props}
16
  transition:name="main" transition:animate={slide({ duration: 150 })}>
17
  <StarlightHead {...Astro.props}><slot /></StarlightHead>
18
</VtbotStarlight>
19

20
{/* update this one to whatever image you want to show as a loading indicator */}
21
<LoadingIndicator top="80px" right="16px" src="/favicon.svg" />
22

23
{/* As an alterative to the LoadingIndicator: */}
24
<ProgressBar />
25
<style is:global>
26
  .swup-progress-bar {
27
    background: linear-gradient(
28
      to bottom,
29
      var(--sl-color-accent),
30
      var(--sl-color-accent-high),
31
      var(--sl-color-accent)
32
    );
33
    height: 5px;
34
  }</style>
35

36
<style is:global>
37
  /* Slow down Chrome's default animation */
38
  ::view-transition-group(root) {
39
    animation-duration: 300ms;
40
  }
41

42
  /* Do not slide over the sidebars */
43
  ::view-transition-group(main) {
44
    overflow: hidden;
45
  }
46
  /* For non-native-view-transition browsers */
47
  .main-pane {
48
    overflow: hidden;
49
  }
50

51
  /* let title headings morph into each other */
52
  main h1 {
53
    view-transition-name: title-heading;
54
  }
55
  ::view-transition-group(title-heading) {
56
    animation-duration: 0.3s;
57
  }
58
</style>

Optional Features

This section shows how to add features from the optional feature list. This has just two entries right now but will soon grow further.

Loading indicator

Independent of the Starlight support, The Bag provides loading indicators for you to choose from. The above example contains

the indicator that makes your favicon flash happily in the top right corner during loading (<LoadingIndicator />)
as well as the <ProgressBar /> with some basic styling.

Choose one of those.

Eliminate Pseudo-Scrolling

The default morph animations might look irritating when applied to elements that are larger than the current viewport. This is typical the case if you add an animation to your main area. There is a whole section on the effect and possible solution in this Jotter.

If you just want to get rid of it, add the following to your Head component:

1
---
2
//...
3
import PageOffset from 'astro-vtbot/components/PageOffset.astro';
4
---
5
...
6
<PageOffset name="main" />

For details on the PageOffset component see its description.

Page Order Directions

In the overview, I teased that it might be nice if the direction of the view transition would depend on the page order. Normally, whenever you click on a link, Astro plays a forward animation and when you hit the browser back key, you see a backward animation.

If you have previous and next page links on the bottom of your page, clicking them starts forward animations.
Clicking page 1, page 2, page 1 in the sidebar in this order gives you three forward animations.

This would not make a difference if you use the default fade animation as it looks the same forwards and backwards. But the default slide animation for example has a direction. And maybe your special Starlight animation has one, too.

The Bag has a component called <PageOrder /> that you can add to your Head component. It automatically changes the order of normal navigation and history traversals. If you navigate to a page that is further down in the sidebar, that will be a forward navigation. If you navigate to a page further up, this is back. If not both, the from and the to page are found in the sidebar, direction retains its original value.

1
---
2
//...
3
import PageOrder from 'astro-vtbot/components/starlight/PageOrder.astro';
4
---
5
...
6
<PageOrder />

All Astro animations support forward and backward out of the box. But what, if you click on a link to your current page? Then the <PageOrder /> component sets a third direction called stay. The default animations interpret unknown directions as forward. This is usually fine and you are all set!

If you want to add a special animation for your the stay direction, …

… you can do so by adding CSS for it:

1
...
2
<style is:global>
3
  @keyframes stay-refresh {
4
      0% { opacity: 1; }
5
      1% { opacity: 1; transform: translateY(0px); }
6
     99% { opacity: 1; transform: translateY(100px); }
7
    100% { opacity: 0; }
8
  }
9
  [data-astro-transition='stay']::view-transition-old(main) {
10
    animation: stay-refresh 0.2s ease-in-out both;
11
  }
12
  [data-astro-transition='stay']::view-transition-new(main) {
13
    animation: stay-refresh 0.1s 0.2s reverse ease-in-out both;
14
  }
15
  [data-astro-transition-fallback='old'][data-astro-transition='stay'] main {
16
    animation: stay-refresh 0.2s ease-in-out both;
17
  }
18
  [data-astro-transition-fallback='new'][data-astro-transition='stay'] main {
19
    animation: stay-refresh 0.1s reverse ease-in-out both;
20
  }
21
</style>

Another page in the Jotter explains why you need four definitions and what purpose they serve. The rules with ::view-transition-...(main) address the transition named “main” for browsers that do have native view transition support. The last two rules address the <main> element for browsers that don’t.

Refrain from merging rules with pseudo-elements with rules without pseudo-elements. Browsers treat unknown elements or properties as errors and discard the entire rule, even if they could understand half of the selector.

Additional Morph Effects

Now it’s getting funny! I made a component that I could use to make the headings of the pages stand out during view transitions. It is called AutoNameSelected.

Without any parameters it selects all headings on all pages and assigns the view transition names vtbot-hx-0, vtbot-hx-1, …. This has the effect that the n-th heading on the current page and the n-th heading on the next page from a view-transition-group. The headings are cut out of the page context and the old heading morphs into the new heading when navigating.

You see this effect on the Jotter pages.

After I added some configuration options to the component, I saw much more potential. Have a look at the image gallery demo, which uses AutoNameSelected to shuffle image tiles around. Or take a look at the table of contents to the right which has a similar effect. Here is how that is done:

1
---
2
//...
3
import AutoNameSelected from 'astro-vtbot/components/AutoNameSelected.astro';
4
---
5
...
6
<AutoNameSelected selector="starlight-toc li" prefix="vtbot-toc" shuffle={true} />

Event though this component was crafted as part of The Bag’s Stalivht support, it is a general purpose component that can well be used beyond Astro.

In case you want to change the default behavior of the sidebar, the 👜 Bag of Tricks ✨ offers some switches and utility functions.

Replace the Sidebar Content

You can have the content of the sidebar replaced on each navigation. To do this, add the replaceSidebarContent attribute to the VtbotStarlight tag in your Head component.

1
<VtbotStarlight {...Astro.props} replaceSidebarContent>

This will swap in the sidebar content from the next page when you navigate. This allows you to have different sidebar content on your pages. It also allows you to control the state of the categories, i.e. whether they are shown open or collapsed, with your static page content. Auto-opening and auto-scrolling to the current page marker is not disabled by this switch.

Retain the Current Page Marker

If you want to take control over the current page marker yourself, you can switch of the default update by adding the retainCurrentPageMarker attribute to the VtbotStarlight tag in your Head component. This will also disable auto-opening and auto-scrolling to the current page marker.

1
<VtbotStarlight {...Astro.props} retainCurrentPageMarker>

On navigation, this leaves the current page marker as is. If you already set the replaceSidebarContent attribute, you do not need retainCurrentPageMarker. To assist you in updating the page marker yourself, The Bag offers these utility functions:

1
// Return the <a> element inside the sidebar that best fits the URL parameter
2
export function sidebarEntry(url: URL): HTMLAnchorElement | null {...}
3

4
// Clears the current page marker in the sidebar without setting a new one
5
export function clearCurrentPageMarker(): void {...}
6

7
// Clears the current page marker and then sets it to the entry that best fits the URL
8
export function updateCurrentPageMarker(url: URL): void {...}
9

10
// Opens all nested categories of a sidebar entry. Without url parameter, opens the entry of the current page marker. With url parameter opens the corresponding sidebarEntry(url). You can set scrollIntoView to false to prevent the entry to be scrolled into view.
11
export function openCategory(url?: URL, scrollIntoView = true): void {...}

Here best fit in general means exact match, but if there is none, it also looks for the longest common prefix.

To use the utility functions, import one ore more from astro-vtbot/components/starlight/utils:

1
---
2
---
3
<script>
4
  import { clearCurrentPageMarker, updateCurrentPageMarker, sidebarEntry } from 'astro-vtbot/components/starlight/utils';
5
  ...
6
</script>

Re-initialize Starlight Pages

For most Starlight sites, the following topic is not relevant. We talk about an issue with re-initialization of Starlight pages when there are view transitions that originate from outside the Starlight pages. To be affected by this problem you must fulfill the following conditions:

Under the same origin (= protocol, hostname, port): You have additional pages that are not part of your current Starlight content, or yiu even have a second Starlight site.
Those pages also have view transitions enabled.

The issue here is that the Starlight pages are perfectly initialized on the first load, which is a full page load. Later navigation within the Starlight realm is also fine, as we use the <ReplacementSwap /> component to keep the app state up to date. But view transitions that come from outside the Starlight’s realm are soft reloads that cannot properly re-initialize the app state.

The Bag’s website has this structure. If that also sounds like your setup, use the <BorderControl /> component to define and protect your Starlight realm by forcing full page loads on incoming view transitions.

Here is the setting used by the Jotter to protect it from incoming view transitions from demos or reusable components.

1
---
2
//...
3
import BorderControl from 'astro-vtbot/components/BorderControl.astro';
4

5
---
6
...
7
<BorderControl fence={{ inside: ['/jotter/'] }} />

Make Some Noise

I apologize if the sounds of the jotter bother you, but I just couldn’t resist triggering something other than animations through the life cycle events of the astro view transitions. Maybe you have a more subtle sound file than the one the jotter uses. If you want to try it out, it’s really easy:

1
---
2
//...
3
import SwapSound from 'astro-vtbot/components/SwapSound.astro';
4

5
---
6
...
7
<SwapSound src="/large-steampunk-factory-machine-188048.mp3" />

For further details see the description of the <SwapSound /> component.

Custom Combo Options

What follows is a yet more extended version of the extended configuration example, but without the styling examples. It is not meant to be copied over into your Head but rather as a showcase what optional components you might mix and match in your own Head component. The section with the optional components is highlighted.

1
---
2
import type { Props } from '@astrojs/starlight/props';
3
import StarlightHead from '@astrojs/starlight/components/Head.astro';
4
import VtbotStarlight from 'astro-vtbot/components/starlight/Base.astro';
5
import LoadingIndicator from 'astro-vtbot/components/LoadingIndicator.astro';
6
import ProgressBar from 'astro-vtbot/components/ProgressBar.astro';
7
import PageOffset from 'astro-vtbot/components/PageOffset.astro';
8
import PageOrder from 'astro-vtbot/components/starlight/PageOrder.astro';
9
import AutoNameSelected from 'astro-vtbot/components/AutoNameSelected.astro';
10
import SwapSound from 'astro-vtbot/components/SwapSound.astro';
11
import BorderControl from 'astro-vtbot/components/BorderControl.astro';
12
---
13

14
{/* Define a view transition animation for `<main>`*/}
15
<VtbotStarlight {...Astro.props} transition:name="main" transition:animate="slide">
16
  <StarlightHead {...Astro.props}><slot /></StarlightHead>
17
</VtbotStarlight>
18

19
{/* Customize what image you want to show where */}
20
<LoadingIndicator top="80px" right="16px" src="/favicon.svg" />
21

22
{/* As an alterative to the LoadingIndicator: */}
23
<ProgressBar />
24
<style is:global>
25
  .swup-progress-bar {
26
    background: linear-gradient(
27
      to bottom,
28
      var(--sl-color-accent),
29
      var(--sl-color-accent-high),
30
      var(--sl-color-accent)
31
    );
32
    height: 5px;
33
  }
34
</style>
35

36
{/* Decent transitions for scrolled down pages */}
37
<PageOffset name="main" />
38

39
{/* Make animation direction based on the order of the pages in the sidebar */}
40
<PageOrder />
41

42
{/* Without further configuration, make headings stand out during view transitions.*/}
43
{/* Can be used to declaratively add view transition names,*/}
44
{/* which opens a door to all kinds of funny thing. */}
45
<AutoNameSelected />
46

47
{/* If you have other pages in this project,*/}
48
{/* protect the starlight part from incoming view transitions */}
49
<BorderControl fence={{ inside: ['/jotter/', '/blog/'] }} />
50

51
{/* If you want to swap the sound of the page transition */}
52
<SwapSound src="/path/to/sound.mp3" />

Friendly Neighbor

Currently, The Bag’s support for view transitions is aware of and compatible with the following plugins you might use with your starlight site: *

HiDeoo/starlight-image-zoom (https://starlight-image-zoom.vercel.app/↗)
@lorenzo_lewis/starlight-utils (f.k.a. starlight-mul ti-sidebar) (https://starlight-utils.pages.dev/↗)
HiDeoo/starlight-blog (https://starlight-blog-docs.vercel.app/↗)
@astrojs/starlight-docsearch (https://starlight.astro.build/guides/site-search/#algolia-docsearch↗)

I plan to continue to support compatibility with these packages in future versions of the 👜 Bag of Tricks ✨.

Known Issues

There are some facts that you should be aware of. None of them is a real obstacle on using The Bag’s Starlight support.

View Transitions into Your Starlight Site from the Outside

If you link to a page of your Starlight site from the outside, you should not use view transitions, but do a full page load instead. This way, your Starlight site will be properly initialized This is also important if you create a link between two Starlight sites.

The website of The Bag automatically intercepts all links that return to the /jotter/ and does a full page load. The Bag will soon offer a reusable component to facilitate that.

Not tested with arbitrary Starlight options

Starlight supports a lot of different config options. The Bags view transition support is so far only tested with a few typical combinations.

Multilingual Starlight sites force a complete reload of the page if you select a different language. This is a good thing, as the app frame changes completely and has to be reloaded anyway.

As always, feedback is very welcome!

I look forward to your feedback! Did it work for you? What were the biggest hurdles? What are you looking for?

Get in touch on Discord or discuss on the 👜 Bag of Tricks ✨‘s github page↗. And of course I would be more than happy if you would like to sponsor my projects↗! Made with 💖👜✨!

Here is a pointer↗ to background information on how overriding components works. ↩
Assuming .mjs as the extension here but .ts would also be fine, of course! ↩