Configuration

Use the all-in-one Icons integration.

astro.config.mjs

import Icons from 'starlight-plugin-icons'

export default {
  integrations: [
    Icons({
      // Toggle features
      sidebar: true,          // override Sidebar component
      codeblock: true,        // code block icons + CSS
      extractSafelist: true,  // scan content for icons safelist

      // Pass-through Starlight config (icon field supported in sidebar)
      starlight: {
        sidebar: [
          { label: 'Guide', items: [{ icon: 'i-ph:rocket-launch-duotone', label: 'Intro', slug: 'guide/intro' }] },
        ],
      },
    }),
  ],
}

Or specify the Astro integration and the Starlight plugin manually.

astro.config.mjs

import starlight from '@astrojs/starlight'
import { starlightIconsPlugin, starlightIconsIntegration } from 'starlight-plugin-icons'

export default {
  integrations: [
    starlight({ plugins: [starlightIconsPlugin()] }),
    starlightIconsIntegration(),
  ],
}

Using with starlight-sidebar-topics

Both this plugin and starlight-sidebar-topics need to override the Sidebar component. To make them work together, create a custom Sidebar that combines both.

This plugin provides SidebarSublist for sidebar item icons, and Topics/TopicsDropdown for sidebar topics.

1. Create a custom Sidebar

Topic list

src/components/starlight/Sidebar.astro

---
import MobileMenuFooter from '@astrojs/starlight/components/MobileMenuFooter.astro'
import SidebarPersister from '@astrojs/starlight/components/SidebarPersister.astro'
import SidebarSublist from 'starlight-plugin-icons/components/starlight/SidebarSublist.astro'
import Topics from 'starlight-plugin-icons/components/starlight/Topics.astro'

const { hasSidebar, sidebar } = Astro.locals.starlightRoute
---

{hasSidebar && <Topics />}

<SidebarPersister>
  <SidebarSublist sublist={sidebar} />
</SidebarPersister>

<div class="md:sl-hidden">
  <MobileMenuFooter />
</div>

Topic dropdown

src/components/starlight/Sidebar.astro

---
import MobileMenuFooter from '@astrojs/starlight/components/MobileMenuFooter.astro'
import SidebarPersister from '@astrojs/starlight/components/SidebarPersister.astro'
import SidebarSublist from 'starlight-plugin-icons/components/starlight/SidebarSublist.astro'
import TopicsDropdown from 'starlight-plugin-icons/components/starlight/TopicsDropdown.astro'

const { hasSidebar, sidebar } = Astro.locals.starlightRoute
---

{hasSidebar && <TopicsDropdown />}

<SidebarPersister>
  <SidebarSublist sublist={sidebar} />
</SidebarPersister>

<div class="md:sl-hidden">
  <MobileMenuFooter />
</div>

2. Configure Starlight

Point the Sidebar component to the custom one, and use defineSidebar() to wrap each topic’s items. Topics support UnoCSS icons as well.

astro.config.mjs

import Icons, { defineSidebar } from 'starlight-plugin-icons'
import starlightSidebarTopics from 'starlight-sidebar-topics'

export default {
  integrations: [
    Icons({
      sidebar: true,
      starlight: {
        components: {
          Sidebar: './src/components/starlight/Sidebar.astro',
        },
        plugins: [
          starlightSidebarTopics([
            {
              label: 'Docs',
              icon: 'i-ph:book-open-duotone',
              link: '/getting-started/',
              items: defineSidebar([
                { icon: 'i-ph:hand-waving-duotone', label: 'Intro', slug: 'getting-started/intro' },
              ]),
            },
          ]),
        ],
      },
    }),
  ],
}