Overrides Reference
You can override Starlightâs built-in components by providing paths to replacement components in Starlightâs components configuration option.
This page lists all components available to override and links to their default implementations on GitHub.
Learn more in the Guide to Overriding Components.
Components
Section titled âComponentsâThese components are rendered inside each pageâs <head> element.
They should only include elements permitted inside <head>.
Default component: Head.astro
Component rendered inside each pageâs <head>.
Override this component as a last resort.
Prefer the head config option, the head frontmatter field, or a route data middleware to customize the route data rendered by the default component if possible.
ThemeProvider
Section titled âThemeProviderâDefault component: ThemeProvider.astro
Component rendered inside <head> that sets up dark/light theme support.
The default implementation includes an inline script and a <template> used by the script in <ThemeSelect />.
Accessibility
Section titled âAccessibilityâSkipLink
Section titled âSkipLinkâDefault component: SkipLink.astro
Component rendered as the first element inside <body> which links to the main page content for accessibility.
The default implementation is hidden until a user focuses it by tabbing with their keyboard.
These components are responsible for laying out Starlightâs components and managing views across different breakpoints. Overriding these comes with significant complexity. When possible, prefer overriding a lower-level component.
PageFrame
Section titled âPageFrameâDefault component: PageFrame.astro
Named slots: header, sidebar
Layout component wrapped around most of the page content.
The default implementation sets up the headerâsidebarâmain layout and includes header and sidebar named slots along with a default slot for the main content.
It also renders <MobileMenuToggle /> to support toggling the sidebar navigation on small (mobile) viewports.
MobileMenuToggle
Section titled âMobileMenuToggleâDefault component: MobileMenuToggle.astro
Component rendered inside <PageFrame> that is responsible for toggling the sidebar navigation on small (mobile) viewports.
TwoColumnContent
Section titled âTwoColumnContentâDefault component: TwoColumnContent.astro
Named slot: right-sidebar
Layout component wrapped around the main content column and right sidebar (table of contents). The default implementation handles the switch between a single-column, small-viewport layout and a two-column, larger-viewport layout.
These components render Starlightâs top navigation bar.
Default component: Header.astro
Header component displayed at the top of every page.
The default implementation displays <SiteTitle />, <Search />, <SocialIcons />, <ThemeSelect />, and <LanguageSelect />.
SiteTitle
Section titled âSiteTitleâDefault component: SiteTitle.astro
Component rendered at the start of the site header to render the site title. The default implementation includes logic for rendering logos defined in Starlight config.
Default component: Search.astro
Component used to render Starlightâs search UI. The default implementation includes the button in the header and the code for displaying a search modal when it is clicked and loading Pagefindâs UI.
When pagefind is disabled, the default search component will not be rendered.
However, if you override Search, your custom component will always be rendered even if the pagefind configuration option is false.
This allows you to add UI for alternative search providers when disabling Pagefind.
SocialIcons
Section titled âSocialIconsâDefault component: SocialIcons.astro
Component rendered in the site header including social icon links.
The default implementation uses the social option in Starlight config to render icons and links.
ThemeSelect
Section titled âThemeSelectâDefault component: ThemeSelect.astro
Component rendered in the site header that allows users to select their preferred color scheme.
LanguageSelect
Section titled âLanguageSelectâDefault component: LanguageSelect.astro
Component rendered in the site header that allows users to switch to a different language.
Global Sidebar
Section titled âGlobal SidebarâStarlightâs global sidebar includes the main site navigation. On narrow viewports this is hidden behind a drop-down menu.
Sidebar
Section titled âSidebarâDefault component: Sidebar.astro
Component rendered before page content that contains global navigation.
The default implementation displays as a sidebar on wide enough viewports and inside a drop-down menu on small (mobile) viewports.
It also renders <MobileMenuFooter /> to show additional items inside the mobile menu.
MobileMenuFooter
Section titled âMobileMenuFooterâDefault component: MobileMenuFooter.astro
Component rendered at the bottom of the mobile drop-down menu.
The default implementation renders <ThemeSelect /> and <LanguageSelect />.
Page Sidebar
Section titled âPage SidebarâStarlightâs page sidebar is responsible for displaying a table of contents outlining the current pageâs subheadings. On narrow viewports this collapse into a sticky, drop-down menu.
PageSidebar
Section titled âPageSidebarâDefault component: PageSidebar.astro
Component rendered before the main pageâs content to display a table of contents.
The default implementation renders <TableOfContents /> and <MobileTableOfContents />.
TableOfContents
Section titled âTableOfContentsâDefault component: TableOfContents.astro
Component that renders the current pageâs table of contents on wider viewports.
MobileTableOfContents
Section titled âMobileTableOfContentsâDefault component: MobileTableOfContents.astro
Component that renders the current pageâs table of contents on small (mobile) viewports.
Content
Section titled âContentâThese components are rendered in the main column of page content.
Default component: Banner.astro
Banner component rendered at the top of each page.
The default implementation uses the pageâs banner frontmatter value to decide whether or not to render.
ContentPanel
Section titled âContentPanelâDefault component: ContentPanel.astro
Layout component used to wrap sections of the main content column.
PageTitle
Section titled âPageTitleâDefault component: PageTitle.astro
Component containing the <h1> element for the current page.
Implementations should ensure they set id="_top" on the <h1> element as in the default implementation.
DraftContentNotice
Section titled âDraftContentNoticeâDefault component: DraftContentNotice.astro
Notice displayed to users during development when the current page is marked as a draft.
FallbackContentNotice
Section titled âFallbackContentNoticeâDefault component: FallbackContentNotice.astro
Notice displayed to users on pages where a translation for the current language is not available. Only used on multilingual sites.
Default component: Hero.astro
Component rendered at the top of the page when hero is set in frontmatter.
The default implementation shows a large title, tagline, and call-to-action links alongside an optional image.
MarkdownContent
Section titled âMarkdownContentâDefault component: MarkdownContent.astro
Component rendered around each pageâs main content. The default implementation sets up basic styles to apply to Markdown content.
The Markdown content styles are also exposed in @astrojs/starlight/style/markdown.css and scoped to the .sl-markdown-content CSS class.
These components are rendered at the bottom of the main column of page content.
Default component: Footer.astro
Footer component displayed at the bottom of each page.
The default implementation displays <LastUpdated />, <Pagination />, and <EditLink />.
LastUpdated
Section titled âLastUpdatedâDefault component: LastUpdated.astro
Component rendered in the page footer to display the last-updated date.
EditLink
Section titled âEditLinkâDefault component: EditLink.astro
Component rendered in the page footer to display a link to where the page can be edited.
Pagination
Section titled âPaginationâDefault component: Pagination.astro
Component rendered in the page footer to display navigation arrows between previous/next pages.