Skip to content
HiDeoo

Add social links with custom icons to Starlight

- Updated on -

Starlight has built-in support for displaying social links with an icon in the website header using the Starlight social configuration option. But sometimes, you may want to add a social link with a custom icon that is not part of Starlight’s built-in icons.

Using component overrides, you can add social links with custom icons 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 Default from '@astrojs/starlight/components/SocialIcons.astro'
---


<!-- Render the default social links. -->
<Default><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 new social link and render its custom SVG icon before or after the existing social links:

src/components/SocialIcons.astro
---
import Default from '@astrojs/starlight/components/SocialIcons.astro'
---


<!-- Add social link with its custom SVG icon and a label. -->
<a href="https://example.com" rel="me" class="sl-flex">
  <span class="sr-only">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.