PageWithTags

The PageWithTags component wraps your content and displays tags at configurable positions (top, bottom, or both).

See live demo →

Wrapper component with positioning control

<PageWithTags position="both">
  <YourContent />
</PageWithTags>

• Automatically fetches data from frontmatter or accepts tagIds
• Wraps content via <slot /> so your content goes inside
• Supports position control with top, bottom, or both
• Adds separator line and “Tags” title for bottom position
• Best for: Layout templates where you want tags to frame content

Import

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

Props

Prop	Type	Default	Description
tagIds	string[]	-	Specific tag IDs to display
tags	ProcessedTag[]	-	Pre-fetched tag objects (for advanced use)
position	'top' | 'bottom' | 'both'	'bottom'	Where to display tags
showTitle	boolean	true	Show “Tags” heading (bottom only)
frontmatter	{ tags?: string[] }	undefined	Override frontmatter tags programmatically

Note

If neither tagIds nor tags is provided, the component automatically reads tags from the page’s frontmatter.

Basic Usage

Display tags from the current page’s frontmatter:

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

<PageWithTags>
  <h1>My Page Title</h1>
  <p>Page content goes here...</p>
</PageWithTags>

Specific Tags

Display specific tags by ID:

<PageWithTags tagIds={['configuration', 'guide']}>
  <p>Content with specific tags...</p>
</PageWithTags>

Positions

Bottom (Default)

Tags appear after the content with a separator:

<PageWithTags position="bottom">
  <slot />
</PageWithTags>

Top

Tags appear before the content:

<PageWithTags position="top">
  <slot />
</PageWithTags>

Both

Tags appear at both top and bottom:

<PageWithTags position="both">
  <slot />
</PageWithTags>

Without Title

Hide the “Tags” heading at the bottom:

<PageWithTags showTitle={false}>
  <slot />
</PageWithTags>

Combined Options

<PageWithTags
  tagIds={['components', 'reference', 'advanced']}
  position="both"
  showTitle={false}
>
  <article>
    <h1>Component Guide</h1>
    <p>Content here...</p>
  </article>
</PageWithTags>

Styling

The component adds margin and border styling:

• Top position: Margin below tags
• Bottom position: Margin above tags with a top border separator

Custom Styling

Override the default styles:

.fb-page-tags {
  margin: 1rem 0;
}

.fb-page-tags--top {
  margin-bottom: 2rem;
}

.fb-page-tags--bottom {
  border-top: 2px solid var(--sl-color-accent);
  padding-top: 1rem;
}

Hiding Tags

The component respects the hideTags frontmatter property. When hideTags: true is set in a page’s frontmatter, the component renders nothing (only the slotted content is displayed):

---
title: Internal Documentation
tags:
  - configuration
  - troubleshooting
hideTags: true
---

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

<PageWithTags position="both">
  <!-- Tags won't display at top or bottom because hideTags is true -->
  <p>This content will still render, but without tags.</p>
</PageWithTags>

The page will still appear in tag listings (e.g., /tags/configuration), but tags won’t be displayed on the page itself. This is useful for internal documentation or pages where you want tag-based organization without visible tag badges.

PageWithTags vs PageTags

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

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

When to Use PageWithTags

Choose PageWithTags when you need:

• Tags frame your content automatically through content wrapping
• Enforces consistent positioning across pages (great for layout components)
• Lets you specify which tags to display via tagIds
• Provides visual separation with a built-in separator line and optional “Tags” title

<PageWithTags position="both">
  <article>
    <slot />
  </article>
</PageWithTags>

When to Use PageTags

Choose PageTags when you want:

• Drop <PageTags /> anywhere in your MDX for simplicity
• Place tags exactly where you want in your content
• Display tags inline as part of content flow

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

Components vs Auto-Generated Pages

It’s important to understand the difference between components you use in your content and the pages automatically generated by the plugin:

Aspect	PageWithTags (Component)	/tags Index Page
Type	Component you import	Auto-generated route
Purpose	Wrap content with tags	List all tags in system
Shows	Tags for a single page	All tags with stats & cloud
Data	Auto-fetched or via tagIds	Fetches all tags automatically
Localization	Hardcoded title (customizable)	Fully localized UI
Usage	<PageWithTags>...</PageWithTags>	Visit /tags URL

Auto-Generated Pages

The plugin automatically creates these routes:

• /tags is the index page listing all tags with stats, tag cloud, and alphabetical navigation
• /tags/[tag-slug] are individual tag pages showing all pages with that tag

These pages are fully localized and styled - you don’t need to create them yourself.