Custom Topic List

By default, the Starlight Sidebar Topics plugin overrides the Starlight built-in <Sidebar> component to display a list of topics above the default sidebar content.

The plugin also exposes a route data object that contains all the information required to render a custom topic list in your project.

What is route data?

Similar to Starlight route data, the route data provided by the Starlight Sidebar Topics plugin is an object containing the information about all the configured topics in your project. It includes information like a list of all the topics, the label of each topic, and if the current page is part of a specific topic.

To learn more about all the available properties in the route data object, check the starlightSidebarTopics section.

Using route data

You can access the route data object provided by the Starlight Sidebar Topics plugin from the Astro.locals.starlightSidebarTopics global in Astro components:

example.astro

---
const { topics } = Astro.locals.starlightSidebarTopics
//        ^ The list of all the topics in your project.
---

Create a custom topic list

A custom topic list can be created using the route data object provided by the Starlight Sidebar Topics plugin.

1. Prevent the Starlight Sidebar Topics plugin from rendering the built-in topic list by overriding the <Sidebar> component in astro.config.mjs:

   astro.config.mjs

   // @ts-check
   import { defineConfig } from 'astro/config'
   import starlight from '@astrojs/starlight'
   
   export default defineConfig({
     integrations: [
       starlight({
         title: 'My Docs',
         components: {
           // Override the `<Sidebar>` component.
           Sidebar: './src/components/Sidebar.astro',
         },
       }),
     ],
   })

2. Create an Astro component for the <Sidebar> component override:

   This component can render anything you want, or only reuse the default Starlight built-in <Sidebar> component.

   src/components/Sidebar.astro

   ---
   import Default from '@astrojs/starlight/components/Sidebar.astro'
   ---
   
   <Default><slot /></Default>

3. Create an Astro component to replace the topic list based on the Astro.locals.starlightSidebarTopics route data object:

   docs/src/components/CustomTopicList.astro

   ---
   const { topics } = Astro.locals.starlightSidebarTopics
   ---
   
   <nav>
     {
       topics.map((topic) => (
         <a href={topic.link} aria-current={topic.isCurrent ? 'page' : false}>
           {topic.label}
         </a>
       ))
     }
   </nav>

   The basic example above iterates over all the topics in the route data object and renders a list of links to each topic:

   Preview

   Documentation Demo Starlight Docs

   Up to you to customize the list as you want to match the look and feel of your project.

4. Choose the Starlight component that should be overridden to render your custom topic list. You can find a full list of components in the Starlight Overrides Reference.

   Tip

   Not sure which component you need to override? Use the interactive Starlight Overrides Map to discover the names of Starlight’s UI components.

   The following example overrides the <SiteTitle> component to render the custom topic list next to the site title in the header

   src/components/SiteTitle.astro

   ---
   import Default from '@astrojs/starlight/components/SiteTitle.astro'
   import CustomTopicList from './CustomTopicList.astro'
   ---
   
   {/* Render the default site title. */}
   <Default><slot /></Default>
   {/* Render the custom topic list. */}
   <CustomTopicList />

For reference, you can also check the built-in topic list component in the Starlight Sidebar Topics plugin source code which also relies on the route data object to render the default list of topics.

Custom topic lists can also be third-party components developed and shared by the community like the starlight-sidebar-topics-dropdown package exposing a dropdown menu to navigate between topics.

starlightSidebarTopics

The starlightSidebarTopics object has the following properties:

topics

A list of all the configured topics in your project.

Each topic object has the following properties:

label

type: string

The label of the topic.

link

type: string

The link to the topic’s content.

isCurrent

type: boolean

Indicates if the current page is part of the topic.

icon

type: string | undefined

The name of an optional icon associated with the topic set to one of Starlight’s built-in icons. You can use the Starlight <Icon> component to render the icon.

badge

type: { text: string; variant: 'note' | 'danger' | 'success' | 'caution' | 'tip' | 'default' } | undefined

The optional badge associated with the topic. You can use the Starlight <Badge> component to render the badge.

isPageWithTopic

type: boolean

Indicates if the current page is associated with a topic or not.