# How to Add Custom SVG Icons to the AppBar Using icons.yaml in Astro Big Doc

> Easily add custom SVG icons to your Astro Big Doc AppBar using the icons.yaml file. Learn how to configure and integrate your SVGs for seamless navigation.

- Repository: [Micro Web Stacks/astro-big-doc](https://github.com/microwebstacks/astro-big-doc)
- Tags: how-to-guide
- Published: 2026-03-07

---

**Add a YAML entry to [`content/icons.yaml`](https://github.com/microwebstacks/astro-big-doc/blob/main/content/icons.yaml) pointing to an SVG in `src/assets`, optionally set `align: right`, and the create-menu integration automatically merges it into the AppBar navigation.**

The **Astro Big Doc** theme generates its top navigation bar (the **AppBar**) from a build-time menu JSON. By editing [`content/icons.yaml`](https://github.com/microwebstacks/astro-big-doc/blob/main/content/icons.yaml), you can inject custom SVG icons into this bar without touching core layout code. The `create-menu` integration ([`src/integrations/create_menu.js`](https://github.com/microwebstacks/astro-big-doc/blob/main/src/integrations/create_menu.js)) reads this file and appends entries to the generated menu, while `src/layout/AppBar.astro` renders them via the `Icon` component.

## Step 1 – Store Your SVG Files in the Assets Directory

Place your custom SVG files inside **`src/assets/`**. The theme's asset pipeline and the `SvgIcons` component (`src/components/svgicons.astro`) both reference this directory for static files.

For example, save your logo as:

```

src/assets/mylogo.svg

```

## Step 2 – Configure Icons in content/icons.yaml

Create or edit **[`content/icons.yaml`](https://github.com/microwebstacks/astro-big-doc/blob/main/content/icons.yaml)** and add a map entry for each icon you want to display. The `icon` field should match the filename (without extension) of the SVG stored in `src/assets`.

```yaml
- icon: mylogo
  align: right
  link: https://example.com

```

- **`icon`**: Required. The base name of the SVG file in `src/assets`.
- **`align`**: Optional. Set to `right` to push the icon to the right side of the AppBar. Omit or set to `left` for left alignment.
- **`link`**: Optional. The URL navigated to when the icon is clicked.

## Step 3 – Understanding the Build Integration

The **create-menu** integration ([`src/integrations/create_menu.js`](https://github.com/microwebstacks/astro-big-doc/blob/main/src/integrations/create_menu.js)) automatically merges [`icons.yaml`](https://github.com/microwebstacks/astro-big-doc/blob/main/icons.yaml) into the site menu at build time. Lines 63-68 load the file and push its contents into the `sorted_items` array that becomes the AppBar menu:

```javascript
const icons_file = join(content_path,"icons.yaml")
if (await exists(icons_file)) {
    const icons_list = await load_yaml_abs(icons_file)
    sorted_items.push(...icons_list)   // Icons become menu items
}

```

This happens during the `astro:build:setup` hook, ensuring your icons are present in the static JSON menu consumed by the layout components.

## Step 4 – How the AppBar Renders Icons

The AppBar component (`src/layout/AppBar.astro`) receives the menu from [`layout_utils.js`](https://github.com/microwebstacks/astro-big-doc/blob/main/layout_utils.js) and filters items into left and right arrays based on the `align` property:

```javascript
// From src/layout/layout_utils.js
let base_menu = get_base_menu()
const menu = get_active_appbar_menu(base_menu, Astro.url.pathname)
const left_side  = menu.filter(item => !item.align || item.align !== "right")
const right_side = menu.filter(item => item.align === "right")

```

When iterating over menu items, `AppBar.astro` checks for the `icon` field and renders the `Icon` component:

```astro
{item.icon && <Icon filename={item.icon} />}

```

## Step 5 – Extending the Icon Component for Custom SVGs

By default, `src/components/icon.astro` hard-codes support for specific PNG icons (`github` and `search`). To render arbitrary SVGs from `src/assets`, modify `icon.astro` to dynamically load SVG files using the same pattern as `svgicons.astro`:

```astro
---
import { readFile } from 'fs/promises';
import { exists } from '@/libs/assets';
import { config } from '@/config';
import { join } from 'node:path';

export interface Props {
  filename: string;
}
const { filename } = Astro.props as Props;
const filepath = join(config.rootdir, `src/assets/${filename}.svg`);
const innerHTML = await exists(filepath) ? await readFile(filepath) : "<svg/>";
---
<Fragment set:html={innerHTML} />

```

After this modification, the `Icon` component will render any SVG placed in `src/assets` whose name matches the `icon` field in [`icons.yaml`](https://github.com/microwebstacks/astro-big-doc/blob/main/icons.yaml).

## Complete Working Example

1. **Save your SVG**:

   ```bash
   # src/assets/company-logo.svg

   <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor">
     <path d="M12 2L2 22h20L12 2z"/>
   </svg>
   ```

2. **Configure icons.yaml**:

   ```yaml
   - icon: company-logo
     align: right
     link: https://my-company.com
   ```

3. **Update icon.astro** (if not already generic) with the dynamic SVG loader code shown in Step 5.

4. **Run the dev server**:

   ```bash
   pnpm run dev
   ```

The company logo now appears on the right side of the AppBar and links to the specified URL.

## Summary

- Place SVG files in **`src/assets/`** to make them available to the theme.
- Define icons in **[`content/icons.yaml`](https://github.com/microwebstacks/astro-big-doc/blob/main/content/icons.yaml)** using the `icon`, `align`, and `link` fields.
- The **[`create_menu.js`](https://github.com/microwebstacks/astro-big-doc/blob/main/create_menu.js)** integration automatically merges YAML entries into the AppBar menu at build time.
- **`AppBar.astro`** filters items by alignment and renders them via the **`Icon`** component.
- Extend **`src/components/icon.astro`** to support arbitrary SVGs beyond the default hard-coded icons.

## Frequently Asked Questions

### Can I add multiple custom icons to the AppBar?

Yes. [`content/icons.yaml`](https://github.com/microwebstacks/astro-big-doc/blob/main/content/icons.yaml) accepts a list of entries. Each item with an `icon` field becomes a separate icon in the AppBar. You can mix left-aligned and right-aligned icons by setting or omitting the `align: right` property on each entry.

### What happens if the SVG file is missing from src/assets?

If `src/components/icon.astro` is updated with the dynamic loader pattern shown in Step 5, the component renders an empty `<svg/>` element when the file is not found. This prevents build errors while allowing the menu structure to remain intact. Always verify that the `icon` value in [`icons.yaml`](https://github.com/microwebstacks/astro-big-doc/blob/main/icons.yaml) matches the filename (without extension) in `src/assets`.

### Do I need to restart the dev server after editing icons.yaml?

Yes. The [`create_menu.js`](https://github.com/microwebstacks/astro-big-doc/blob/main/create_menu.js) integration runs during the Astro build process to generate the static menu JSON. While Astro's dev server handles many hot updates, changes to YAML data files consumed by integrations typically require a restart to regenerate the menu structure. Run `pnpm run dev` again to see new icons appear.

### Can I use PNG or other image formats instead of SVG?

The default `Icon` component in `src/components/icon.astro` is designed for SVG files when using the dynamic loader pattern. If you need to support PNGs or other formats, you would need to modify the component to handle different file extensions or use an `<img>` tag instead of inline SVG. However, SVG is recommended for AppBar icons because it scales cleanly and supports currentColor for theme consistency.