starlight-custom-component

Starlight Custom Components

Starlight's built-in UI can be extended or replaced by registering your own Astro components. Use this when CSS is not enough or you need behavioral changes.

When to Use

• Changing a Starlight UI element that CSS alone cannot address
• Adding new UI alongside an existing Starlight element (e.g., a banner above the header)
• Replacing a built-in component with different markup or behavior
• Conditionally rendering different UI on specific pages

When Not to Use

• Simple color or font changes — use starlight-theme instead
• Adding documentation content (pages, sidebars) — use starlight-base instead

Mindset

Starlight's UI is a set of named slots. You swap slot implementations, not DOM nodes.

1. Named slots, not selectors. You register a replacement .astro file for a named component slot in astro.config.mjs. No CSS selector is involved — you replace the entire component rendering.
2. Wrap, don't replace. Import the default component and render it inside your override to add behavior without duplicating Starlight's markup. This keeps you compatible with future Starlight updates.
3. Page data lives in Astro.locals, not props. All route metadata is available via Astro.locals.starlightRoute. See overrides-reference.md for all available properties.

Step-by-Step: Override a Component

Step 1 — Identify the slot name from the Overrides Reference. Common ones: Header, Footer, PageTitle, Sidebar, TableOfContents, Hero, Pagination. Use the Overrides Map to visually locate UI areas.

Step 2 — Create the component:

---
// src/components/CustomFooter.astro
---
<footer>
  <p>Built with Starlight</p>
</footer>

Step 3 — Register in astro.config.mjs:

starlight({
  components: {
    Footer: './src/components/CustomFooter.astro',
  },
})