How to create a horizontal progress indicator for your Starlight site

A beautiful cover image with the text "Progress Bar"

Jun 10, 2025 • 2 min read • 300 words

In this post, we would like to show you how FrostyBee created a clean horizontal progress indicator for Starlight sites.

Prerequisites

You will need to have an existing Starlight website.

Create the progress indicator component

Let’s create a new component called ProgressIndicator.astro in the src/components/ directory. This component will be responsible for rendering the progress indicator.

First, let’s take a look at a classic solution using JavaScript.

We create a container which spans across the whole width with the progress bar <div> inside. The width of the inner <div> is the updated whenever the user scrolls (and when the page loads) to reflect the current scroll position.

1
<div class="progress-scroll-container" aria-hidden="true">
2
  <div id="progress-scroll"></div>
3
</div>
4

5
<script>
6
  window.addEventListener("scroll", function () {
7
    updateProgressScroll();
8
  });
9
  window.addEventListener("load", function () {
10
    updateProgressScroll();
11
  });
12

13
  function updateProgressScroll() {
14
    if (document) {
15
      const progressScroll = document.getElementById("progress-scroll");
16
      if (progressScroll) {
17
        var scrollTop = window.scrollY || document.documentElement.scrollTop;
18
        var scrollHeight =
19
          document.documentElement.scrollHeight - window.innerHeight;
20
        var progress = (scrollTop / scrollHeight) * 100;
21
        progressScroll.style.width = progress + "%";
22
      }
23
    }
24
  }
25
</script>
26

17 collapsed lines
27
<style>
28
  html:is(:not([data-has-hero]), [data-has-sidebar], [data-has-toc]) .progress-scroll-container {
29
    position: fixed;
30
    top: var(--sl-nav-height);
31
    left: 0;
32
    height: 0.25rem;
33
    width: 100%;
34
    background-color: transparent;
35
    z-index: 3;
36
  }
37

38
  #progress-scroll {
39
    height: 100%;
40
    width: 0px;
41
    background-color: var(--sl-color-accent-high);
42
  }
43
</style>
44

45
<style is:global>
46
  #starlight__on-this-page--mobile {
47
    margin-top: 0.25rem;
48
  }
49
</style>

In the hidden lines is the styling which makes sure that the progress bar looks like a typical progress bar. It is also suited to Starlight because the bar is automatically hidden when the site has no sidebar and table of contents, but a hero element as most landing pages do.

One thing to point out is what the global CSS (line 45) does: It pushes the mobile table of contents dropdown menu down to create more whitespace to the progress bar. This is a personal preference and you can remove it if you want.

Starlight Override

Now we can use this component in a Starlight override. In this case it makes sense to override the Header.astro component like this:

1
---
2
import Default from "@astrojs/starlight/components/Header.astro";
3
import ScrollIndicator from "./ScrollIndicator.astro";
4
---
5

6
<Default><slot /></Default>
7
<ScrollIndicator />

Do not forget to add this component override to your astro.config.mjs file:

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

4
export default defineConfig({
5
  integrations: [
6
    starlight({
7
      title: 'My Docs with a Progress Indicator',
8
      components: {
9
        // Override the default `Header` component.
10
        Header: './src/components/Header.astro',
11
      },
12
    }),
13
  ],
14
});

Source Code

You can find the whole project code on GitHub and in this Stackblitz example.

Conclusion

With this setup, the progress indicator will be displayed on every page (except landing pages) of your Starlight site. 🥳