TagBadge

The TagBadge component renders a single tag as a styled pill-shaped badge with optional icon and count.

See live demo →

Import

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

Props

Prop	Type	Default	Description
tagId	string	-	Tag ID to display (fetches data automatically)
tag	ProcessedTag	-	Pre-fetched tag object (for advanced use)
size	'small' | 'medium' | 'large'	'medium'	Badge size
variant	'solid' | 'outline' | 'ghost'	'solid'	Visual style
showCount	boolean	false	Show page count
showIcon	boolean	true	Show tag icon
clickable	boolean	true	Render as link

Note

You must provide either tagId or tag. Using tagId is recommended as it handles data fetching automatically.

Basic Usage

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

<TagBadge tagId="authentication" />

That’s it! The component fetches tag data automatically.

Variants

Solid (Default)

Filled background with the tag’s color:

<TagBadge tagId="authentication" variant="solid" />

Outline

Bordered with transparent background:

<TagBadge tagId="authentication" variant="outline" />

Ghost

Subtle background tint:

<TagBadge tagId="authentication" variant="ghost" />

Sizes

<TagBadge tagId="authentication" size="small" />
<TagBadge tagId="authentication" size="medium" />
<TagBadge tagId="authentication" size="large" />

With Count

Show the number of pages with this tag:

<TagBadge tagId="authentication" showCount />

Without Icon

Hide the tag icon:

<TagBadge tagId="authentication" showIcon={false} />

Non-Clickable

Render as a span instead of a link:

<TagBadge tagId="authentication" clickable={false} />

Multiple Tags

Display several tags together:

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

<div style="display: flex; gap: 0.5rem; flex-wrap: wrap;">
  <TagBadge tagId="authentication" />
  <TagBadge tagId="rest-api" />
  <TagBadge tagId="webhooks" variant="outline" />
</div>

Advanced: Pre-fetched Tag

For advanced use cases where you already have tag data:

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

const { tags } = Astro.locals.starlightTags;
const authTag = tags.get('authentication');
---

<TagBadge tag={authTag} variant="outline" showCount />

Styling

The component uses CSS custom properties that inherit from Starlight’s theme:

• Tag color from tags.yml is applied via --tag-color
• Falls back to --sl-color-accent if no color specified

Custom Styling

Override styles using CSS:

/* In your custom CSS */
.fb-tag {
  font-family: var(--sl-font-mono);
}

.fb-tag--solid {
  box-shadow: none;
}