# Icon Reference

URL: /bengal/docs/reference/icons/
Section: reference
Description: SVG icon library with theme-aware styling

---

> For a complete page index, fetch /bengal/llms.txt.

**130 theme-aware SVG icons** powered by [Phosphor Icons](https://phosphoricons.com/). All icons adapt to light/dark mode using `currentColor`.

## Syntax

| Syntax | Use | Example |
|--------|-----|---------|
| `:::{icon} name` | Block | `:::{icon} terminal :size: 48 :::` |
| `{icon}`name`` | Inline | `{icon}`terminal`` |
| `{icon}`name:size`` | Inline + size | `{icon}`terminal:16`` |
| `{icon}`name:size:class`` | Inline + size + class | `{icon}`terminal:24:icon--primary`` |

**Aliases**: `{svg-icon}`

## Options

| Option | Default | Description |
|--------|---------|-------------|
| `:size:` | 24 | Icon size in pixels |
| `:class:` | — | CSS classes (`icon--primary`, `icon--success`, etc.) |
| `:aria-label:` | — | Accessibility label for screen readers |

## Color Classes

| Class | Preview |
|-------|---------|
| `icon--primary` | {icon}`star:20:icon--primary` |
| `icon--secondary` | {icon}`bookmark:20:icon--secondary` |
| `icon--success` | {icon}`check:20:icon--success` |
| `icon--warning` | {icon}`warning:20:icon--warning` |
| `icon--danger` | {icon}`error:20:icon--danger` |
| `icon--info` | {icon}`info:20:icon--info` |
| `icon--muted` | {icon}`question:20:icon--muted` |
| `icon--example` | {icon}`flask:20:icon--example` |

---

## Icon Gallery

### Bengal

| Icon | Name | Description |
|------|------|-------------|
| {icon}`bengal-rosette:24` | `bengal-rosette` | Bengal signature rosette |
| {icon}`terminal:24` | `terminal` | CLI/commands |
| {icon}`docs:24` | `docs` | Documentation |
| {icon}`bug:24` | `bug` | Bugs/errors |

### Navigation

| Icon | Name | Description |
|------|------|-------------|
| {icon}`search:24` | `search` | Search |
| {icon}`magnifying-glass:24` | `magnifying-glass` | Search (alternative) |
| {icon}`menu:24` | `menu` | Menu toggle |
| {icon}`close:24` | `close` | Close/dismiss |
| {icon}`x:24` | `x` | Close (alternative) |
| {icon}`chevron-right:24` | `chevron-right` | Navigate forward |
| {icon}`chevron-left:24` | `chevron-left` | Navigate back |
| {icon}`chevron-down:24` | `chevron-down` | Expand |
| {icon}`chevron-up:24` | `chevron-up` | Collapse |
| {icon}`caret-right:24` | `caret-right` | Caret forward |
| {icon}`caret-left:24` | `caret-left` | Caret back |
| {icon}`caret-down:24` | `caret-down` | Caret expand |
| {icon}`caret-up:24` | `caret-up` | Caret collapse |
| {icon}`arrow-right:24` | `arrow-right` | Arrow forward |
| {icon}`arrow-left:24` | `arrow-left` | Arrow back |
| {icon}`arrow-up:24` | `arrow-up` | Arrow up |
| {icon}`arrow-clockwise:24` | `arrow-clockwise` | Refresh/reload |
| {icon}`link:24` | `link` | Internal link |
| {icon}`external:24` | `external` | External link |
| {icon}`house:24` | `house` | Home |
| {icon}`compass:24` | `compass` | Explore/discover |
| {icon}`map:24` | `map` | Map/sitemap |
| {icon}`sidebar:24` | `sidebar` | Sidebar toggle |
| {icon}`sidebar-simple:24` | `sidebar-simple` | Sidebar (simple) |

### Content

| Icon | Name | Description |
|------|------|-------------|
| {icon}`file:24` | `file` | File/document |
| {icon}`file-text:24` | `file-text` | Text document |
| {icon}`file-code:24` | `file-code` | Code file |
| {icon}`file-py:24` | `file-py` | Python file |
| {icon}`file-js:24` | `file-js` | JavaScript file |
| {icon}`file-ts:24` | `file-ts` | TypeScript file |
| {icon}`folder:24` | `folder` | Folder/directory |
| {icon}`code:24` | `code` | Code block |
| {icon}`function:24` | `function` | Function/method |
| {icon}`notepad:24` | `notepad` | Notes/text |
| {icon}`book:24` | `book` | Book/guide |
| {icon}`book-open:24` | `book-open` | Open book |
| {icon}`article:24` | `article` | Article/blog post |
| {icon}`newspaper:24` | `newspaper` | News/updates |
| {icon}`copy:24` | `copy` | Copy |
| {icon}`edit:24` | `edit` | Edit |
| {icon}`pencil:24` | `pencil` | Pencil/write |
| {icon}`feather:24` | `feather` | Light writing |
| {icon}`bookmark:24` | `bookmark` | Bookmark |
| {icon}`tag:24` | `tag` | Tag/label |
| {icon}`image:24` | `image` | Image |
| {icon}`list:24` | `list` | List |
| {icon}`layers:24` | `layers` | Layers/stack |
| {icon}`stack:24` | `stack` | Stack/architecture |
| {icon}`funnel:24` | `funnel` | Filter (funnel) |
| {icon}`filter:24` | `filter` | Filter |
| {icon}`tree-structure:24` | `tree-structure` | Hierarchy/tree |

### Status & Admonitions

| Icon | Name | Description |
|------|------|-------------|
| {icon}`check:24` | `check` | Success/check |
| {icon}`check-circle:24` | `check-circle` | Success (circled) |
| {icon}`success:24` | `success` | Success admonition |
| {icon}`info:24` | `info` | Information |
| {icon}`lightbulb:24` | `lightbulb` | Ideas/tips |
| {icon}`note:24` | `note` | Note admonition |
| {icon}`tip:24` | `tip` | Tip admonition |
| {icon}`warning:24` | `warning` | Warning |
| {icon}`caution:24` | `caution` | Caution |
| {icon}`danger:24` | `danger` | Danger |
| {icon}`error:24` | `error` | Error |
| {icon}`example:24` | `example` | Example |
| {icon}`question:24` | `question` | Help/question |
| {icon}`sparkle:24` | `sparkle` | New/sparkle |

### Actions

| Icon | Name | Description |
|------|------|-------------|
| {icon}`download:24` | `download` | Download |
| {icon}`upload:24` | `upload` | Upload |
| {icon}`trash:24` | `trash` | Delete |
| {icon}`star:24` | `star` | Favorite |
| {icon}`heart:24` | `heart` | Like |
| {icon}`share:24` | `share` | Share |
| {icon}`eye:24` | `eye` | View/preview |
| {icon}`zoom-in:24` | `zoom-in` | Zoom in |
| {icon}`zoom-out:24` | `zoom-out` | Zoom out |
| {icon}`enlarge:24` | `enlarge` | Expand/enlarge |
| {icon}`reset:24` | `reset` | Reset |
| {icon}`recycle:24` | `recycle` | Recycle/refresh |
| {icon}`wrench:24` | `wrench` | Tools/fix |
| {icon}`zap:24` | `zap` | Quick action |
| {icon}`lightning:24` | `lightning` | Fast/speed |
| {icon}`rocket:24` | `rocket` | Launch/start |

### Development & Git

| Icon | Name | Description |
|------|------|-------------|
| {icon}`git-branch:24` | `git-branch` | Git branch |
| {icon}`git-commit:24` | `git-commit` | Git commit |
| {icon}`code-branch:24` | `code-branch` | Code branch |
| {icon}`package:24` | `package` | Package/module |
| {icon}`cube:24` | `cube` | Block/component |
| {icon}`puzzle-piece:24` | `puzzle-piece` | Integration/plugin |
| {icon}`puzzle:24` | `puzzle` | Puzzle (alias) |
| {icon}`flask:24` | `flask` | Testing/experiments |
| {icon}`workflow:24` | `workflow` | Workflow/pipeline |

### Infrastructure & Security

| Icon | Name | Description |
|------|------|-------------|
| {icon}`server:24` | `server` | Server |
| {icon}`container:24` | `container` | Container/Docker |
| {icon}`hard-drives:24` | `hard-drives` | Storage/drives |
| {icon}`database:24` | `database` | Database |
| {icon}`cloud:24` | `cloud` | Cloud/hosting |
| {icon}`network:24` | `network` | Network/connectivity |
| {icon}`cpu:24` | `cpu` | CPU/performance |
| {icon}`shield:24` | `shield` | Security |
| {icon}`lock:24` | `lock` | Locked/private |
| {icon}`key:24` | `key` | Key/authentication |
| {icon}`briefcase:24` | `briefcase` | Business/work |

### Time & Location

| Icon | Name | Description |
|------|------|-------------|
| {icon}`clock:24` | `clock` | Time |
| {icon}`timer:24` | `timer` | Timer/countdown |
| {icon}`calendar:24` | `calendar` | Date |
| {icon}`pin:24` | `pin` | Location |
| {icon}`globe:24` | `globe` | Global/international |
| {icon}`translate:24` | `translate` | Translation/i18n |

### Theme & Settings

| Icon | Name | Description |
|------|------|-------------|
| {icon}`settings:24` | `settings` | Settings |
| {icon}`palette:24` | `palette` | Theme |
| {icon}`sun:24` | `sun` | Light mode |
| {icon}`moon:24` | `moon` | Dark mode |
| {icon}`monitor:24` | `monitor` | System/display |

### Users

| Icon | Name | Description |
|------|------|-------------|
| {icon}`user:24` | `user` | User/profile |
| {icon}`users:24` | `users` | Multiple users/team |
| {icon}`graduation-cap:24` | `graduation-cap` | Education/learning |

### Social & Platforms

| Icon | Name | Description |
|------|------|-------------|
| {icon}`github-logo:24` | `github-logo` | GitHub |
| {icon}`twitter-logo:24` | `twitter-logo` | Twitter/X |
| {icon}`linkedin-logo:24` | `linkedin-logo` | LinkedIn |
| {icon}`facebook-logo:24` | `facebook-logo` | Facebook |

### AI Providers

| Icon | Name | Description |
|------|------|-------------|
| {icon}`ai-chatgpt:24` | `ai-chatgpt` | ChatGPT |
| {icon}`ai-claude:24` | `ai-claude` | Claude |
| {icon}`ai-copilot:24` | `ai-copilot` | GitHub Copilot |
| {icon}`ai-gemini:24` | `ai-gemini` | Google Gemini |

### Mid-Century Modern

| Icon | Name | Description |
|------|------|-------------|
| {icon}`atomic:24` | `atomic` | Atomic age symbol |
| {icon}`starburst:24` | `starburst` | Sputnik starburst |
| {icon}`boomerang:24` | `boomerang` | Retro boomerang |

---

## Quick Preview

All icons at 32px:

**Navigation**: {icon}`menu:32` {icon}`search:32` {icon}`close:32` {icon}`chevron-up:32` {icon}`chevron-down:32` {icon}`chevron-left:32` {icon}`chevron-right:32` {icon}`arrow-left:32` {icon}`arrow-right:32` {icon}`link:32` {icon}`external:32` {icon}`house:32` {icon}`compass:32`

**Status**: {icon}`check:32` {icon}`check-circle:32` {icon}`info:32` {icon}`lightbulb:32` {icon}`warning:32` {icon}`error:32` {icon}`note:32` {icon}`tip:32` {icon}`danger:32` {icon}`sparkle:32`

**Files**: {icon}`file:32` {icon}`file-text:32` {icon}`file-code:32` {icon}`file-py:32` {icon}`file-js:32` {icon}`file-ts:32` {icon}`folder:32` {icon}`code:32` {icon}`function:32` {icon}`notepad:32` {icon}`book:32` {icon}`article:32` {icon}`newspaper:32`

**Actions**: {icon}`download:32` {icon}`upload:32` {icon}`trash:32` {icon}`star:32` {icon}`heart:32` {icon}`share:32` {icon}`eye:32` {icon}`wrench:32` {icon}`rocket:32` {icon}`zap:32` {icon}`lightning:32`

**Development**: {icon}`git-branch:32` {icon}`git-commit:32` {icon}`code-branch:32` {icon}`package:32` {icon}`cube:32` {icon}`puzzle-piece:32` {icon}`flask:32` {icon}`workflow:32`

**Infrastructure**: {icon}`server:32` {icon}`container:32` {icon}`hard-drives:32` {icon}`database:32` {icon}`cloud:32` {icon}`network:32` {icon}`cpu:32` {icon}`shield:32` {icon}`lock:32` {icon}`key:32`

**Time & Location**: {icon}`clock:32` {icon}`timer:32` {icon}`calendar:32` {icon}`pin:32` {icon}`globe:32` {icon}`translate:32`

**Theme**: {icon}`settings:32` {icon}`palette:32` {icon}`sun:32` {icon}`moon:32` {icon}`monitor:32`

**Users**: {icon}`user:32` {icon}`users:32` {icon}`graduation-cap:32` {icon}`briefcase:32`

**Social**: {icon}`github-logo:32` {icon}`twitter-logo:32` {icon}`linkedin-logo:32`

**AI**: {icon}`ai-chatgpt:32` {icon}`ai-claude:32` {icon}`ai-copilot:32` {icon}`ai-gemini:32`

**Bengal**: {icon}`bengal-rosette:32` {icon}`terminal:32` {icon}`docs:32` {icon}`bug:32`

**Mid-Century**: {icon}`atomic:32` {icon}`starburst:32` {icon}`boomerang:32`

**Structure**: {icon}`layers:32` {icon}`stack:32` {icon}`tree-structure:32` {icon}`filter:32` {icon}`feather:32`

---

## Custom Icons

Bengal supports **theme-aware icon resolution** — add your own icons or override defaults without forking the theme.

### Resolution Order

Icons are resolved in priority order (first match wins):

1. **Site theme**: `site/themes/{theme}/assets/icons/{name}.svg`
2. **Theme icons**: `bengal/themes/{theme}/assets/icons/{name}.svg`
3. **Parent theme**: `bengal/themes/{parent}/assets/icons/{name}.svg`
4. **Bengal defaults**: `bengal/themes/default/assets/icons/{name}.svg`

### Adding Custom Icons

Create an icons directory in your theme:

```tree
your-project/
└── themes/
    └── my-theme/
        └── assets/
            └── icons/
                ├── company-logo.svg   # New icon
                ├── custom-badge.svg   # New icon
                └── warning.svg        # Overrides default
```

Then use with the standard syntax:

```markdown
{icon}`company-logo:24`
{icon}`custom-badge:32:icon-primary`
```

### Overriding Default Icons

To replace a default icon, add a file with the same name:

```tree
themes/my-theme/assets/icons/
└── warning.svg    # Your custom warning icon
```

All uses of `{icon}`warning`` will now render your version.

### Disabling Default Fallback

To use **only** your icons (no Phosphor fallback), set `extend_defaults` to false in your `theme.yaml`:

```yaml
# themes/my-theme/theme.yaml
name: my-theme

icons:
  extend_defaults: false  # Only theme icons available
```

:::{caution}
With `extend_defaults: false`, any icon not in your theme will show a missing icon indicator.
:::

### SVG Format Requirements

Icons should follow this format for proper theme integration:

```xml
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" fill="none">
  <title>Icon Name</title>
  <path fill="currentColor" d="..."/>
</svg>
```

| Attribute | Value | Purpose |
|-----------|-------|---------|
| `viewBox` | `0 0 256 256` | Phosphor's native size (scales via width/height) |
| `fill` on `<svg>` | `none` | Prevents background fill |
| `fill` on `<path>` | `currentColor` | Inherits text color (theme-aware) |
| `<title>` | Icon name | Accessibility |

Icons are automatically sized via the `:size:` parameter and inherit colors from the current theme.

### Icon Source

Bengal uses [Phosphor Icons](https://phosphoricons.com/) as its base icon set:

- **MIT License**: Free for commercial use
- **Consistent design**: All icons follow the same design principles
- **Theme-aware**: Uses `currentColor` for automatic light/dark mode support

## Related

- [Formatting Directives](/docs/reference/directives/formatting/) — Buttons with icons
- [Assets](/docs/theming/assets/) — Asset pipeline for custom icons
- [Content Authoring](/docs/content/authoring/) — Using icons in content