TagSidebar

The TagSidebar component displays popular tags in a compact format for quick tag navigation. Despite its name, this component can be placed anywhere in your site, not just the sidebar.

Import

import { TagSidebar } from 'starlight-tags/components';

Props

Prop	Type	Default	Description
`limit`	`number`	`10`	Maximum number of tags to display
`sortBy`	`'count' \| 'priority' \| 'alphabetical'`	`'count'`	Sort order for tags
`showCount`	`boolean`	`true`	Show page count badge next to each tag
`title`	`string`	Localized `'Popular Tags'`	Section heading (uses `starlightTags.popularTags` translation)
`collapsible`	`boolean`	`true`	Enable collapsible behavior
`collapsed`	`boolean`	`false`	Start with sidebar collapsed

Placement Options

Create a sidebar component override:

---
import Default from '@astrojs/starlight/components/Sidebar.astro';
import { TagSidebar } from 'starlight-tags/components';
---

<Default {...Astro.props} />
<TagSidebar limit={8} sortBy="count" />

Then register the override in your astro.config.mjs:

import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      components: {
        Sidebar: './src/components/SidebarOverride.astro',
      },
    }),
  ],
});

In the Table of Contents

Create a TOC component override:

---
import Default from '@astrojs/starlight/components/TableOfContents.astro';
import { TagSidebar } from 'starlight-tags/components';
---

<Default {...Astro.props} />
<TagSidebar title="Browse Tags" collapsible={false} />

components: {
  TableOfContents: './src/components/TableOfContentsOverride.astro',
}

In MDX Content

Use the component directly in any MDX page:

---
title: My Page
---

import { TagSidebar } from 'starlight-tags/components';

Some content here...

<TagSidebar limit={5} showCount={false} />

Customization Examples

Limit Number of Tags

Show only the top 5 tags:

<TagSidebar limit={5} />

Sort Alphabetically

<TagSidebar sortBy="alphabetical" title="Tags A-Z" />

Sort by Priority

Uses the priority field from your tag definitions:

<TagSidebar sortBy="priority" title="Featured Tags" />

Hide Page Counts

<TagSidebar showCount={false} />

Custom Title

<TagSidebar title="Browse by Topic" />

Combined Options

<TagSidebar
  limit={8}
  sortBy="count"
  showCount={true}
  title="Top Topics"
/>

Styling

The component uses Starlight’s CSS variables for consistent theming:

--sl-color-bg-nav - Background color
--sl-color-gray-5 - Border color
--sl-color-gray-2 - Link text color
--sl-color-accent - Hover and link accent color
--sl-color-white - Title and count text color

The component automatically adapts to light and dark themes.

How It Works

The TagSidebar component:

Fetches all tags from middleware (Astro.locals.starlightTags)
Sorts tags based on the sortBy prop (default: by page count, descending)
Limits to the specified number of tags
Renders a vertical list with optional count badges
Includes a “View all tags” link to the full tag index

The component renders nothing if no tags are defined in your site.