Override a Starlight component in a Starlight plugin

Starlight plugins offer an easy-to-share and reusable way to customize and extend Starlight, the fully-featured documentation theme built on top of the Astro framework.

This guide will walk you through the process of overriding a Starlight component in a Starlight plugin, enabling you to extend or completely replace its default components.

Prerequisites

You will need to have a Starlight plugin set up. If you don’t have one yet, you can follow the “How to create a Starlight plugin” note to create one or refer to the Starlight documentation for a complete reference.

Override a Starlight component

Export the override

Before you can override a Starlight component in a Starlight plugin, the plugin must export an Astro component that will be used to override the default Starlight component. Check out the “Expose Astro components in a Starlight plugin“ note for more information on how to export an Astro component from a Starlight plugin.

The following example adds a new entry point name ./SearchOverride.astro that points to a SearchOverride.astro file in the plugin’s root directory:

{
  "name": "starlight-plugin-example",
  "version": "0.0.1",
  "license": "MIT",
  "type": "module",
  "exports": {
    ".": "./plugin.ts"
    ".": "./plugin.ts",
    "./SearchOverride.astro": "./SearchOverride.astro"
  },
  "peerDependencies": {
    "@astrojs/starlight": ">=0.34"
  }
}

Add the override to the Starlight configuration

Once the overriding Astro component is exported from the Starlight plugin, it can be used by the Starlight plugin to override a Starlight component using the components option of the Starlight configuration.

To update the user-supplied Starlight configuration in a Starlight plugin, you can use the updateConfig() function provided in the config:setup Starlight plugin configuration setup function.

The following example updates the components option in the user-supplied Starlight configuration to override the default Starlight Search component with the SearchOverride.astro component exported from the starlight-plugin-example package:

import type { StarlightPlugin } from '@astrojs/starlight/types'

export default function starlightPluginExample(): StarlightPlugin {
  return {
    name: 'starlight-plugin-example',
    hooks: {
      'config:setup'({ config, updateConfig, logger }) {
        // If the user already has a custom override for the Search component,
        // don't override it and log a warning with helpful instructions.
        if (config.components?.Search) {
          logger.warn(
            'The Starlight configuration already has a `Search` component override.',
          )
          logger.warn(
            'To use `starlight-plugin-example`, remove the conflicting override.
          )
        } else {
          // Otherwise, add the Search component override to the Starlight config.
          updateConfig({
            components: {
              ...config.components,
              Search: 'starlight-plugin-example/SearchOverride.astro',
            },
          })
        }
      },
    },
  }
}

To learn more about Starlight plugins, check out the “Starlight Plugins by Example” notebook for additional guides and examples.