Starlight’s default UI and configuration options are designed to be flexible and work for a range of content. Much of Starlight’s default appearance can be customized with CSS and configuration options.
When you need more than what’s possible out of the box, Starlight supports building your own custom components to extend or override (completely replace) its default components.
When to override
Overriding Starlight’s default components can be useful when:
- You want to change how a part of Starlight’s UI looks in a way not possible with custom CSS.
- You want to change how a part of Starlight’s UI behaves.
- You want to add some additional UI alongside Starlight’s existing UI.
How to override
Choose the Starlight component you want to override. You can find a full list of components in the Overrides Reference.
This example will override Starlight’s
SocialIconscomponent in the page nav bar.
Create an Astro component to replace the Starlight component with. This example renders a contact link.
Tell Starlight to use your custom component in the
componentsconfiguration option in
Reuse a built-in component
You can build with Starlight’s default UI components just as you would with your own: importing and rendering them in your own custom components. This allows you to keep all of Starlight’s basic UI within your design, while adding extra UI alongside them.
The example below shows a custom component that renders an e-mail link along with the default
When rendering a built-in component inside a custom component:
Astro.propsinto it. This makes sure that it receives all the data it needs to render.
- Add a
<slot />inside the default component. This makes sure that if the component is passed any child elements, Astro knows where to render them.
Use page data
When overriding a Starlight component, your custom implementation receives a standard
Astro.props object containing all the data for the current page.
This allows you to use these values to control how your component template renders.
For example, you can read the page’s frontmatter values as
Astro.props.entry.data. In the following example, a replacement
PageTitle component uses this to display the current page’s title:
Learn more about all the available props in the Overrides Reference.
Only override on specific pages
Component overrides apply to all pages. However, you can conditionally render using values from
Astro.props to determine when to show your custom UI, when to show Starlight’s default UI, or even when to show something entirely different.
In the following example, a component overriding Starlight’s
Footer displays “Built with Starlight 🌟” on the homepage only, and otherwise shows the default footer on all other pages:
Learn more about conditional rendering in Astro’s Template Syntax guide.