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.

Self-contained components

All components handle data fetching automatically. Just pass a tagId or tagIds prop and they fetch the tag data for you. No manual data fetching required!

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:
  • TagBadge
  • TagsList
  • PageTags
  • PageWithTags
  • TagSidebar
  • PrerequisiteChain
• See how to extend the schema for custom tag displays