PageTags

The PageTags component automatically displays tags from the current page’s frontmatter. It’s the easiest way to show tags on your documentation pages.

See live demo →

Self-contained, automatic tag display

• Reads tags automatically from the current page’s frontmatter
• No props required, just drop it in
• Renders as a simple inline/block list of tag badges
• Best for quick tag display anywhere in your MDX

Import

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

Props

Prop	Type	Default	Description
layout	'inline' | 'block'	'inline'	Display layout
variant	'solid' | 'outline' | 'ghost'	'outline'	Badge visual style
size	'small' | 'medium' | 'large'	'small'	Badge size
showIcon	boolean	true	Show tag icons
label	string | boolean	undefined	Pass true for localized default label, or a custom string

Basic Usage

Simply drop the component into any MDX page that has tags in its frontmatter:

---
title: Configuration Guide
tags:
  - configuration
  - guide
  - getting-started
---

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

# Configuration Guide

<PageTags />

Your content here...

Layouts

Inline (Default)

Tags flow with surrounding content:

<PageTags layout="inline" />

Block

Tags take full width with borders:

<PageTags layout="block" />

With Label

Add a text label before the tags. Use true for the localized default (“Tags:”) or pass a custom string:

{/* Use localized default label */}
<PageTags label={true} />

{/* Use custom label */}
<PageTags label="Topics:" />

Renders as: Topics: [tag1] [tag2] [tag3]

Sizes

<PageTags size="small" />
<PageTags size="medium" />
<PageTags size="large" />

Style Variants

<PageTags variant="solid" />
<PageTags variant="outline" />  <!-- Default -->
<PageTags variant="ghost" />

Without Icons

<PageTags showIcon={false} />

Positioning

Place the component where you want tags to appear:

At the Top

---
title: Plugin Development Guide
tags: [plugins, guide]
---

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

<PageTags layout="block" />

# Plugin Development Guide

Content here...

At the Bottom

---
title: Plugin Development Guide
tags: [plugins, guide]
---

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

# Plugin Development Guide

Content here...

---

<PageTags label="Tagged:" />

Multiple Locations

---
title: Plugin Development Guide
tags: [plugins, guide]
---

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

<PageTags layout="block" variant="ghost" />

# Plugin Development Guide

Content here...

---

<PageTags label="Related topics:" size="small" />

Complete Example

---
title: Advanced Plugin Development
description: Complete guide to building custom plugins
tags:
  - plugins
  - advanced
  - guide
  - components
---

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

<PageTags layout="block" variant="outline" size="medium" label="This guide covers:" />

# Advanced Plugin Development

In this guide, you'll learn how to build custom plugins...

## Prerequisites

Before starting, make sure you understand:
- Basic configuration
- Component fundamentals

## Getting Started

...

---

<PageTags label="Topics covered:" size="small" variant="ghost" />

How It Works

The PageTags component:

1. Reads the tags array from the current page’s frontmatter
2. Checks the hideTags frontmatter property
3. Fetches tag data from middleware (Astro.locals.starlightTags)
4. Renders each tag using the TagBadge component

The component renders nothing if:

• No tags are defined in the frontmatter
• hideTags: true is set in the frontmatter

Hiding Tags

Use the hideTags frontmatter property to hide tags on specific pages while still associating the page with those tags:

---
title: Internal Configuration Reference
tags:
  - configuration
  - reference
hideTags: true
---

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

<PageTags />  <!-- Renders nothing because hideTags is true -->

This page is still listed on the /tags/configuration and /tags/reference pages,
but tags aren't displayed here.

This is useful when you want pages to appear in tag listings without displaying the tags on the page itself.

PageTags vs PageWithTags

Wondering which component to use? Here’s a quick comparison:

Feature	PageTags	PageWithTags
Auto-reads frontmatter	Yes	Yes
Accepts tagIds prop	No	Yes
Wraps content	No	Yes (via slot)
Position control	Manual placement	top / bottom / both
Separator line	No	Yes (bottom position)
“Tags” title	No	Optional
Best for	Drop-in tag display	Layout templates

When to Use PageTags

Choose PageTags when you want:

• A simple drop-in solution — just add <PageTags /> anywhere in your MDX
• Full control over placement within your content
• Automatic tag detection from frontmatter with no extra setup

<PageTags />  <!-- That's it! -->

When to Use PageWithTags

Choose PageWithTags when you need:

• Tags that frame your content at the top, bottom, or both
• Consistent tag positioning across multiple pages
• The ability to specify which tags to display via tagIds

<PageWithTags tags={customTags} position="both">
  <YourContent />
</PageWithTags>