Skip to content
HiDeoo

Add custom social links to Starlight

- Updated on -

Starlight has built-in support for displaying many social links to the website header using the Starlight social configuration option. But sometimes, you may want to add a custom social link that is not supported by Starlight or you cannot wait for it to be added.

Using component overrides, you can add custom social links to Starlight like the last one in the following example:

My Docs

Prerequisites

You will need to have an existing Starlight website.

Override the <SocialIcons/> component

Create a custom Astro component to replace the existing <SocialIcons/> built-in component:

src/components/SocialIcons.astro
---
import type { Props } from '@astrojs/starlight/props'
import Default from '@astrojs/starlight/components/SocialIcons.astro'
---


<!-- Render the default social links. -->
<Default {...Astro.props}><slot /></Default>

Configure Starlight to use this new component instead of the built-in one by specifying its path in the components configuration option in your astro.config.mjs file:

astro.config.mjs
import { defineConfig } from 'astro/config'
import starlight from '@astrojs/starlight'


export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      components: {
        // Relative path to the custom component.
        SocialIcons: './src/components/SocialIcons.astro',
      },
    }),
  ],
})

Update the custom component previously created in src/components/SocialIcons.astro to add a custom social link and render its SVG icon before or after the existing social links:

src/components/SocialIcons.astro
---
import type { Props } from '@astrojs/starlight/props'
import Default from '@astrojs/starlight/components/SocialIcons.astro'
---


<!-- Add custom social link with its SVG icon and a label. -->
<a href="https://example.com" rel="me" class="sl-flex">
  <span class="sr-only">Custom Social</span>
  <svg
    aria-hidden="true"
    fill="currentColor"
    height="16"
    width="16"
    viewBox="0 0 24 24"
  >
    <path
      d="m10 17.55-1.77 1.72a2.47 2.47 0 0 1-3.5-3.5l4.54-4.55a2.46 2.46 0 0 1 3.39-.09l.12.1a1 1 0 0 0 1.4-1.43 2.75 2.75 0 0 0-.18-.21 4.46 4.46 0 0 0-6.09.22l-4.6 4.55a4.48 4.48 0 0 0 6.33 6.33L11.37 19A1 1 0 0 0 10 17.55ZM20.69 3.31a4.49 4.49 0 0 0-6.33 0L12.63 5A1 1 0 0 0 14 6.45l1.73-1.72a2.47 2.47 0 0 1 3.5 3.5l-4.54 4.55a2.46 2.46 0 0 1-3.39.09l-.12-.1a1 1 0 0 0-1.4 1.43 2.75 2.75 0 0 0 .23.21 4.47 4.47 0 0 0 6.09-.22l4.55-4.55a4.49 4.49 0 0 0 .04-6.33Z"
    >
    </path>
  </svg>
</a>
<!-- Render the default social links. -->
<Default {...Astro.props}><slot /></Default>


<!-- Add styles to mimic the default links appearance. -->
<style>
  a {
    color: var(--sl-color-text-accent);
    margin: -0.5em;
    padding: 0.5em;
  }


  a:hover {
    opacity: 0.66;
  }
</style>

You can find the complete source code of this guide in this StackBlitz example.