Components Override

The Galaxy theme extends the Starlight Header component by wrapping it with additional functionality like the progress scroll bar.

⚠️ Component Override Warning

When you override the Header component in your project, you may see a warning like this during the build:

A `<Header>` component override is already defined in your Starlight configuration.
To use `starlight-theme-galaxy`, either remove this override or manually render the content from `starlight-theme-galaxy/overrides/GalaxyHeader.astro`.

This warning appears because the Galaxy theme automatically overrides the Header component, and Starlight detects a potential conflict. This is expected behavior and you can safely ignore the warning or follow one of the customization approaches below to resolve it.

Customizing the Header Component

The Galaxy theme uses a clean wrapper approach that extends Starlight’s original Header component. If you need to customize the header further, you can create your own wrapper:

---
// src/components/CustomHeader.astro
import Header from "@astrojs/starlight/components/Header.astro";
import ProgressScroll from "starlight-theme-galaxy/components/ProgressScroll.astro";

// Hide progress scroll on the home page only (works with any base URL).
const baseUrl = import.meta.env.BASE_URL || "/";
const normalizedPath = Astro.url.pathname.endsWith("/")
  ? Astro.url.pathname
  : Astro.url.pathname + "/";
const normalizedBase = baseUrl.endsWith("/") ? baseUrl : baseUrl + "/";
const displayProgressScroll = normalizedPath !== normalizedBase;
---

<!-- Your custom elements before the header -->
<div class="custom-banner">
  Your custom content here
</div>

<!-- Original Starlight Header with all props passed through -->
<Header {...Astro.props} />

<!-- Galaxy theme's progress scroll -->
{displayProgressScroll && <ProgressScroll />}

<!-- Your custom elements after the header -->
<div class="custom-footer">
  Additional custom content
</div>

<style>
  .custom-banner,
  .custom-footer {
    /* Your custom styles */
  }
</style>

Benefits of this approach:

• Uses Starlight’s original Header component (no custom element registration issues)
• Minimal code footprint - only adds what you need
• Automatically gets updates from Starlight
• Clean separation of concerns
• Easy to maintain and debug

Available Components

The Galaxy theme exports the following components that you can import and customize:

• GalaxyHeader.astro : The main header wrapper that extends Starlight’s Header with progress scroll (located in src/overrides/)
• ThemeSelect.astro : Custom theme selector with Galaxy styling
• ProgressScroll.astro : Animated progress bar that shows reading progress
• HeaderButton.astro : Styled button component used in the theme selector

All components can be imported using:

import ComponentName from 'starlight-theme-galaxy/components/ComponentName.astro'

For overrides, use:

import ComponentName from 'starlight-theme-galaxy/overrides/ComponentName.astro'

Customization Tips

1. Preserve functionality: When overriding, make sure to pass through the required props.
2. Maintain accessibility: Keep ARIA labels and keyboard navigation intact.
3. Responsive design: Ensure your customizations work on all screen sizes.
4. Theme consistency: Use Galaxy theme’s CSS variables for consistent styling.

For more information about Starlight’s component override system, see the official documentation.