Components Overview

The starlight-tags plugin exports several Astro components for displaying tags in your documentation pages. All components can be imported from starlight-tags/components.

Available Components

Component	Purpose
`TagBadge`	Display a single tag badge
`TagsList`	Display a list of tags
`PageTags`	Auto-display tags for the current page
`PageWithTags`	Wrapper that adds tags to content
`TagSidebar`	Sidebar widget for popular tags navigation
`PrerequisiteChain`	Display prerequisite learning path

Importing Components

---
title: Authentication Guide
tags:
  - authentication
  - rest-api
---

import { PageTags, TagBadge, TagsList } from 'starlight-tags/components';

# Authentication Guide

<PageTags />

Content here...

Quick Examples

Display Page Tags

The simplest way to show tags on a page:

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

<PageTags />

Single Tag Badge

Display a specific tag:

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

<TagBadge tagId="authentication" />
<TagBadge tagId="rest-api" variant="outline" size="large" />

Tags List

Display multiple tags:

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

<!-- Show all tags -->
<TagsList />

<!-- Show specific tags -->
<TagsList tagIds={['authentication', 'webhooks', 'rest-api']} />

<!-- With options -->
<TagsList layout="grid" showCount limit={6} />

Prerequisite Chain

Show learning path for a topic:

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

<PrerequisiteChain tagId="oauth2" />

Component Props

Each component accepts different props for customization:

Common Props

Prop	Description
`tagId` / `tagIds`	Tag ID(s) to display (fetches data automatically)
`variant`	Visual style: `'solid'`, `'outline'`, or `'ghost'`
`size`	Size: `'small'`, `'medium'`, or `'large'`
`showIcon`	Whether to show tag icons
`showCount`	Whether to show page counts

Style Variants

All tag components support three visual variants:

solid has a filled background with the tag color
outline has a border with transparent background
ghost has a subtle background tint

Advanced: Manual Data Fetching

For advanced use cases (custom filtering, etc.), you can access tag data via middleware:

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

const { allTagsSorted } = Astro.locals.starlightTags;
const popularTags = allTagsSorted.filter(tag => tag.count >= 3);
---

<TagsList tags={popularTags} />

Next Steps

Learn about each component in detail:
See how to extend the schema for custom tag displays