Use third-party icon sets in Starlight

Starlight provides a set of icons that you can use out of the box in your documentation website. The available icons are a limited selection of common icons from the Unicons set which may not be enough for all use cases.

Using third-party icon sets in Starlight is possible and this guide will show you one possible way to do so using unplugin-icons which relies on Iconify with over 200,000 icons from many open source icon sets.

Other alternatives include astro-icon or the Iconify Icon web component ¹.

Prerequisites

You will need to have an existing Starlight website.

Install unplugin-icons

Start by installing the unplugin-icons package:

npm install unplugin-icons @iconify/json

pnpm add unplugin-icons @iconify/json

yarn add unplugin-icons @iconify/json

bun add unplugin-icons @iconify/json

ni unplugin-icons @iconify/json

Configure unplugin-icons

Import the Vite plugin provided by unplugin-icons in your astro.config.mjs file to add it to the vite.plugins array:

import { defineConfig } from 'astro/config'
import starlight from '@astrojs/starlight'
import Icons from 'unplugin-icons/vite'

export default defineConfig({
  integrations: [starlight({ title: 'My Docs' })],
  vite: {
    plugins: [Icons({ compiler: 'astro' })],
  },
})

Add the unplugin-icons type declarations to your tsconfig.json file:

{
  "extends": "astro/tsconfigs/strict",
  "compilerOptions": {
    "types": ["unplugin-icons/types/astro"]
  }
}

Use a custom icon

To use a custom icon, you import it using the ~icons/{set}/{name} path convention and use it in your MDX documentation pages. To figure out the set and name of the icon you want to use, you can use the Iconify icon sets reference page or Icônes website.

For example, this star icon from the Phosphor Icons set can be imported using the ~icons/ph/shooting-star path:

---
title: My content page
---

## My heading

The content of my Starlight page.

import IconStar from '~icons/ph/shooting-star'

<IconStar color="goldenrod" font-size="3rem" aria-hidden />

The above example will render the following content:

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