Local & Iconify icons

Local icons

File layout

Place .svg files under src/icons/ by default (or set iconDir / iconDirs). The name prop is the file path relative to that directory, without the .svg extension.

Directorysrc/
- Directoryicons/
  - logo.svg
  - close.svg
  - Directorylogos/
    astro.svg
    github.svg

The name prop maps directly to the relative path without .svg:

File	`name` value
`src/icons/logo.svg`	`"logo"`
`src/icons/close.svg`	`"close"`
`src/icons/logos/astro.svg`	`"logos/astro"`
`src/icons/logos/github.svg`	`"logos/github"`

---
import { Icon } from "astro-iconset/components";
---

<Icon name="logo" />
<Icon name="logos/astro" />

Naming rules

Use any characters that are valid in a file path: letters, numbers, hyphens (-), underscores (_), and forward slashes for subfolders.
The name is case-sensitive on case-sensitive file systems (Linux, most CI). Logo and logo are different icons.
The .svg extension is never part of the name.
Spaces in file names work but are awkward in name — prefer hyphens.

Multiple directories (merged set)

Pass an array to iconDir to merge several folders into one flat namespace. Icons from every folder use the same naming rules — the path is relative to each root, and keys must be unique across the merged set.

Directorysrc/
- Directoryicons/
  - logo.svg
  - close.svg
- Directoryextra-icons/
  - star.svg
  - badge.svg

File	`name` (merged `local` set)
`src/icons/logo.svg`	`"logo"`
`src/icons/close.svg`	`"close"`
`src/extra-icons/star.svg`	`"star"`
`src/extra-icons/badge.svg`	`"badge"`

icon({
  iconDir: ["src/icons", "src/extra-icons"],
});

Duplicate keys fail the build — for example both src/icons/logo.svg and src/extra-icons/logo.svg resolve to name="logo". Rename one file or switch to iconDirs with prefixes.

Named directories (`iconDirs`)

Map a prefix to each directory. Files are referenced as prefix:name (still without .svg). Different prefixes can reuse the same file name — brand:logo and ui:logo are not a collision.

Directorysrc/
- Directorybrand-icons/
  - logo.svg
  - wordmark.svg
- Directoryui-icons/
  - logo.svg
  - menu.svg
  - close.svg

Same file name in two folders is fine — the prefix keeps them distinct (brand:logo vs ui:logo).

File	`name`
`src/brand-icons/logo.svg`	`"brand:logo"`
`src/brand-icons/wordmark.svg`	`"brand:wordmark"`
`src/ui-icons/logo.svg`	`"ui:logo"`
`src/ui-icons/menu.svg`	`"ui:menu"`
`src/ui-icons/close.svg`	`"ui:close"`

icon({
  iconDirs: {
    brand: "src/brand-icons",
    ui: "src/ui-icons",
  },
});

<Icon name="brand:logo" />
<Icon name="ui:logo" />
<Icon name="ui:menu" />

Files are optimized with SVGO at build time. See svgoOptions to customize the behaviour.

Iconify icon sets

Iconify bundles many open-source sets as @iconify-json/* npm packages. After you install a package, icons are available to the Icon component by set:icon-name.

Find icons

Browse sets on Iconify Icon Sets or Icônes. The identifier shown on those sites is the set:icon-name value to use in name.

Install a set

Example: Material Design Icons (mdi).

npm install @iconify-json/mdi

pnpm add @iconify-json/mdi

yarn add @iconify-json/mdi

Use an icon

---
import { Icon } from "astro-iconset/components";
---

<Icon name="mdi:account" />
<Icon name="mdi:home" size={24} />

You can mix local icons and multiple Iconify sets in the same project.