PrerequisiteChain

The PrerequisiteChain component displays a visual chain of prerequisite topics, useful for showing API migration paths, dependency relationships, or knowledge prerequisites.

See live demo →

Import

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

Props

Prop	Type	Default	Description
tagId	string	-	Tag ID to show prerequisites for
tag	ProcessedTag	-	Pre-fetched tag object (for advanced use)
tagsMap	Map<string, ProcessedTag>	-	Pre-fetched tags map (for advanced use)
showDescription	boolean	true	Show helper text
maxChainLength	number	5	Max prerequisites to show

Note

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

Basic Usage

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

<PrerequisiteChain tagId="oauth2" />

That’s it! The component fetches tag data and builds the chain automatically.

Prerequisites Setup

For this component to display data, your tags need prerequisites defined in tags.yml:

tags.yml

tags:
  api-basics:
    label: "API Basics"
    description: "Introduction to the API"

  authentication:
    label: "Authentication"
    prerequisites:
      - api-basics

  oauth2:
    label: "OAuth 2.0"
    prerequisites:
      - api-basics
      - authentication

Display

The component renders as:

Prerequisites
Complete these topics before starting this content

[API Basics] → [Authentication] → [OAuth 2.0]
                                   You are here

Use Cases

API Migration Paths

Show users how to migrate between API versions:

<PrerequisiteChain tagId="api-v2" />

tags.yml

tags:
  api-v1:
    label: "API v1"
    description: "Legacy API version"

  api-v2:
    label: "API v2"
    prerequisites:
      - api-v1

Learning Paths

Guide users through a sequence of topics:

<PrerequisiteChain tagId="webhooks" />

Without Description

Hide the helper text for a more compact display:

<PrerequisiteChain tagId="webhooks" showDescription={false} />

Limiting Chain Length

For tags with many prerequisites, limit the display:

<PrerequisiteChain tagId="advanced-topic" maxChainLength={3} />

If more prerequisites exist, it shows ”… and X more prerequisites”.

How It Works

1. The component reads the prerequisiteChain computed property from the tag
2. This property is automatically calculated based on the prerequisites field in your tags configuration
3. It resolves the full chain recursively (prerequisites of prerequisites)
4. Tags are displayed in order with arrows between them
5. The current tag is highlighted with “You are here”

Responsive Design

On mobile devices (< 768px):

• The chain displays vertically instead of horizontally
• Arrows rotate 90 degrees to point downward
• “You are here” label adjusts position

Advanced: Pre-fetched Data

For advanced use cases where you already have tag data:

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

const { tags } = Astro.locals.starlightTags;
const currentTag = tags.get('oauth2');
---

{currentTag?.prerequisiteChain?.length > 0 && (
  <PrerequisiteChain tag={currentTag} tagsMap={tags} />
)}

Styling

The component uses Starlight’s CSS variables:

.prerequisite-chain {
  background: var(--sl-color-bg-sidebar);
  border: 1px solid var(--sl-color-hairline-shade);
  border-radius: var(--sl-border-radius);
}

Custom Styling

Override the default styles:

.prerequisite-chain {
  background: var(--sl-color-bg-nav);
  padding: 1.5rem;
}

.prerequisite-chain__arrow {
  color: var(--sl-color-accent);
  font-size: 1.5em;
}

.prerequisite-chain__current::before {
  content: "Current topic";
  color: var(--sl-color-accent);
}

When to Use

This component is ideal for:

• API version migration guides
• SDK setup sequences
• Feature dependency documentation
• Complex workflows with ordered steps
• Any documentation with prerequisite knowledge

It works best when tags have clear prerequisite relationships defined in your tags.yml configuration.