Skip to content

Sidebar Icons

  1. astro.config.mjs
    Icons({
    sidebar: true,
    starlight: { ... },
    })
  2. Set extractSafelist: true to automatically generate a safelist, or if you prefer not to do that, you need to configure UnoCSS to discover the icons.

    Enable extraction and add the cache to .gitignore.

    astro.config.mjs
    Icons({
    sidebar: true,
    extractSafelist: true,
    starlight: { ... },
    })
    .gitignore
    .starlight-icons
  3. Choose any collection. See the Icon Gallery.

    Terminal window
    npm i -D @iconify-json/{collection}

Add an icon field to each sidebar entry.

Format: i-<collection>:<name>


astro.config.mjs
Icons({
starlight: {
sidebar: [
{
label: 'Guides',
items: [
{ icon: 'i-ph:rocket-launch-duotone', label: 'Intro', slug: 'guides/intro' },
],
},
],
},
})

Rendered

Sidebar with icon

Set CSS variables to configure sidebar icon size and spacing.

src/styles/custom.css
:root {
--spi-sidebar-icon-size: 1.25rem;
--spi-sidebar-icon-gap: 0.25rem;
}