> Agent-readable docs index: /llms.txt. Download /docs.zip to grep all markdown files locally.

---
title: Icons
description: Configure the icon library for your docs site.
icon: shapes
---

# Icons

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

## Setting the icon library

```json
{
  "icons": { "library": "lucide" }
}
```

Supported libraries:

| Library       | Description                              |
| ------------- | ---------------------------------------- |
| `fontawesome` | Font Awesome free set (default)          |
| `lucide`      | Clean, consistent icons                  |
| `tabler`      | Accepted by config, but not rendered yet |

## 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:

```jsonc
// 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:

```mdx
---
title: Authentication
icon: lucide:lock
---
```

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

## Using icons in navigation

Groups and anchors accept an `icon` field:

```json
{
  "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:

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

## Finding icon names

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

```bash
# 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 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.


---

*Powered by [holocron.so](https://holocron.so)*