Astro Icon

Astro Icon is a tool designed to simplify working with icons in Astro projects. Key features include:

• Local Icons: Automatically embed your own custom svg files.
• Icon Sets: Full support for all @iconify-json/* packages, allowing you to use thousands of icons from the Iconify ecosystem.
• Intelligent Sprites: Uses deduplicated sprites to provide icons with zero runtime overhead.
• Fully Dynamic: Supports fully dynamic icon references, meaning you can use icon names as strings without needing explicit imports for every icon.

A standard minimal Astro project follows this structure:

• public/: Contains static assets like images that are served directly.
• src/pages/: Contains .astro or .md files. Each file in this directory is automatically exposed as a route based on its filename.
• src/components/: A conventional location for storing Astro, React, Vue, Svelte, or Preact components.
• package.json: Defines project dependencies and scripts.

/
├── public/
├── src/
│   └── pages/
│       └── index.astro
└── package.json

The Sprite component and <Sprite.Provider> wrapper have been removed in v1. The Icon component now automatically optimizes itself into an SVG spritesheet when used multiple times on the same page. Simply use the Icon component directly.

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

<Icon name="building" />

To create a new, minimal Astro project structure, use the npm init astro command with the minimal template flag.

npm init astro -- --template minimal

The Icon component automatically passes the class prop through to the underlying svg element. If you are using the Astro Tailwind integration, you can apply Tailwind utility classes directly to the component.

<Icon name="logo" class="text-xl text-emerald-700" />

Astro Icon supports any open source icon set distributed via Iconify. To use an icon set, you must install its corresponding @iconify-json/* package. Once installed, icons are available using their prefixed ID (e.g., prefix:icon-name).

Warning for server or hybrid output: If your project uses these output modes, every icon that could potentially be referenced may be included in your server's JavaScript bundle by default. See the Deployment guide to optimize bundle size.

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

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

Astro Icon supports custom local SVG icons stored in your project. By default, it looks in src/icons/.

1. Create a directory at src/icons/.
2. Add your .svg files to that directory.
3. Use the Icon component with the name prop matching the filename (without the extension).

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

<!-- Loads the SVG in `/src/icons/filename.svg` -->
<Icon name="filename" />

To use an icon set, identify the set name and install the @iconify-json/ package using your preferred package manager. For example, to install Material Design Icons (mdi), use one of the following commands:

npm install @iconify-json/mdi

# or

pnpm add @iconify-json/mdi

# or

yarn add @iconify-json/mdi

You can target Icon components using the [data-icon] attribute selector.

• To apply styles to every icon in your project, use the [data-icon] selector.
• To apply styles to a specific icon, use the [data-icon="name"] selector, where name is the icon name passed to the component.

<Icon name="twitter" />
<Icon name="mastodon" />

<style>
/* Targets all icons */
[data-icon] {
    font-size: 2rem;
    color: var(--brand-color);
}
</style>

<Icon name="logo" />

<style>
/* Targets only the 'logo' icon */
[data-icon="logo"] {
    font-size: 2rem;
    color: var(--brand-color);
}
</style>

In v1, astro-icon is an Astro integration. You must add it to your astro.config.mjs file to enable its functionality.

import { defineConfig } from "astro/config";
import icon from "astro-icon";

export default defineConfig({
  integrations: [icon()],
});