Icons

Icons appear in the sidebar (next to pages and groups), in components like Cards, and in the navbar.

Setting the icon library

123{
  "icons": { "library": "lucide" }
}

Supported libraries:

Library	Description
`fontawesome`	Font Awesome free set (default)
`lucide`	Clean, consistent icons

Prefixed icon names

Use prefixed icon names so the source library is explicit. This also lets you mix icons from different libraries in the same project:

12345678910// Lucide icons (recommended)
"icon": "lucide:rocket"
"icon": "lucide:shield"

// Font Awesome icons
"icon": "fontawesome:brands:github"
"icon": "fontawesome:solid:compass"

// Plain names resolve against the configured library
"icon": "rocket"  // resolves to lucide:rocket if "icons.library": "lucide"

Using icons in frontmatter

Set an icon on any page via frontmatter:

1234---
title: Authentication
icon: lucide:lock
---

The icon name is resolved against the configured library if no prefix is given.

Groups and anchors accept an icon field:

12345{
  "group": "Security",
  "icon": "lucide:shield",
  "pages": ["security/overview"]
}

Icon object form

For more control, use the object form to specify a library or style per icon. Font Awesome currently resolves the solid, regular, and brands styles:

1234567{
  "icon": {
    "name": "github",
    "library": "fontawesome",
    "style": "brands"
  }
}

Finding icon names

To browse all available icon names, fetch the schema JSONs:

12345# All lucide icon names
curl -s https://holocron.so/schemas/lucide-icons.json | jq '.enum[:10]'

# All fontawesome icon names
curl -s https://holocron.so/schemas/fontawesome-icons.json | jq '.enum[:10]'

Icon colors

Add iconColor to give icons a distinct color. This works everywhere icons are supported: page frontmatter, groups, tabs, anchors, navbar links, and dropdowns.

Named colors use the built-in editorial palette, which adapts to light and dark mode automatically:

Color	Example
`green`	`"iconColor": "green"`
`blue`	`"iconColor": "blue"`
`red`	`"iconColor": "red"`
`purple`	`"iconColor": "purple"`
`orange`	`"iconColor": "orange"`
`yellow`	`"iconColor": "yellow"`
`pink`	`"iconColor": "pink"`

You can also pass any CSS color string directly (hex, rgb, hsl):

1{ "iconColor": "#e11d48" }

In frontmatter

12345---
title: Authentication
icon: lock
iconColor: green
---

In docs.json

Works on groups, tabs, anchors, navbar links, and dropdowns:

12345678910111213141516171819202122{
  "navigation": {
    "tabs": [
      {
        "tab": "API Reference",
        "icon": "code",
        "iconColor": "blue",
        "groups": [...]
      }
    ],
    "global": {
      "anchors": [
        {
          "anchor": "Discord",
          "href": "https://discord.gg/example",
          "icon": "message-circle",
          "iconColor": "purple"
        }
      ]
    }
  }
}

Desaturation

Sidebar page icons with a color are desaturated 30% by default. They go to full saturation when the page is active or on hover. This keeps the sidebar visually clean while still showing color.

Icon consistency

When adding icons, apply them consistently across all siblings at the same level. Inconsistent icon usage looks unfinished and breaks visual rhythm.

Tabs: if one tab has an icon, every tab must have an icon.
Groups: if one sidebar group has an icon, every sibling group in the same tab should too.
Anchors: if one anchor has an icon, all anchors must.
Pages: if one page in a group has a frontmatter icon, all pages in that group should.
Cards: if one <Card> in a <CardGroup> has an icon prop, every card in that group must.

If a group has an icon, avoid using the same icon on the first page in that group. It looks like a duplicate in the navigation tree.

Build-time atlas

Holocron collects all referenced icon names at build time and generates an atlas. Only the icons you actually use are included in the client bundle.