TagSidebar

Esta página aún no está disponible en tu idioma.

The TagSidebar component displays popular tags in a compact sidebar format. It’s designed to be added to Starlight’s sidebar for quick tag navigation.

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`	`'Popular Tags'`	Section heading
`collapsible`	`boolean`	`true`	Enable collapsible behavior
`collapsed`	`boolean`	`false`	Start with sidebar collapsed

To add the TagSidebar to your Starlight site, 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" title="Popular Tags" />

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',
      },
    }),
  ],
});

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.