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 1.
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:
My heading
The content of my Starlight page.
You can find the complete source code of this guide in this StackBlitz example.
Footnotes
-
The Iconify Icon web component retrieves icon data on demand on the client side. ↩