Skip to content
Astro Icon

Customizing Icons

Astro Icon is designed to support custom icons that exist as .svg files in your project. It also supports any open source icon set distributed by Iconify.

Local icons

Add new icons to your site by creating .svg files in /src/icons/. Use sub-folders to organize your files and create multiple sets of icons.

Icons in the /src/icons/ directory can be automatically referenced by their slug, for example:

---
import { Icon } from 'astro-icon/components'
---


<!-- Embed the contents of the `/src/icons/logo.svg` file -->
<Icon name="logo" />


<!-- Embed the contents of the `/src/icons/logos/astro.svg` file -->
<Icon name="logos/astro" />

Local .svg files are automatically optimized with svgo. Specific svgo options can be configured in the integration.

Open Source Icon Sets

Iconify is a project that distributes normalized packages of open source icon sets. After installing an icon set in your project, icons will be automatically available to the Icon component.

Find an icon set

Visit the official Iconify Icon Sets explorer or the popular Icônes app to browse the available icon sets.

Install dependency

After identifying the icon set you would like to use, you must install the corresponding @iconify-json/* package.

As an example, to install the Material Design Icons set, run the following command:

Terminal window
npm install @iconify-json/mdi

Using an icon set

Installed icon sets can be automatically referenced by their prefixed id, for example:

---
import { Icon } from 'astro-icon/components'
---


<!-- Embed the `account` icon from `@iconify-json/mdi` -->
<Icon name="mdi:account" />

Using multiple icon sources

You are not limited to a single icon source!

  • You may mix and match local icons with an @iconify-json/* icon set.
  • You may install multiple @iconify-json/* icon sets.