Getting Started

Astro Iconset adds an Icon component and an Astro integration for local SVGs and Iconify sets. This guide assumes you already have an Astro project. If not, see the Astro installation guide.

1. Install the package

Run astro add to install the package and register the integration automatically:

npm

npx astro add astro-iconset

pnpm

pnpm astro add astro-iconset

Yarn

yarn astro add astro-iconset

Or install manually with your package manager and follow step 2:

npm

npm install astro-iconset

pnpm

pnpm add astro-iconset

Yarn

yarn add astro-iconset

2. Register the integration

Skip this step if you used astro add. Add the integration to astro.config.mjs:

astro.config.mjs

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

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

3. Add icons

Place .svg files under src/icons/ (the default). You may use subfolders — for example src/icons/logos/astro.svg is referenced as logos/astro.

4. Render an icon

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

<Icon name="my-icon" />

If something does not work as expected, open an issue with a minimal reproduction.

Next steps

• Local & Iconify icons — Iconify sets, naming rules, iconDir, iconDirs.
• SVG imports (?icon) — Import a single file with ?icon and pass icon={…}.
• Components — Props, sprites, and is:inline.
• Framework islands — astro-iconset/react, /vue, /svelte, /preact, /solid.
• CSS & styling — data-icon, currentColor, Tailwind, accessibility.
• Configuration — All options with types and defaults.
• Troubleshooting — Icon not found, wrong size, TypeScript errors, SSR issues.

Quick reference

Most common patterns at a glance:

---
import { Icon } from "astro-iconset/components";
import logo from "../assets/logo.svg?icon";
---

<!-- Local SVG from src/icons/close.svg -->
<Icon name="close" />

<!-- Subfolder: src/icons/logos/astro.svg -->
<Icon name="logos/astro" />

<!-- Iconify set (needs @iconify-json/mdi installed) -->
<Icon name="mdi:account" size={24} title="Account" />

<!-- One-off SVG import -->
<Icon icon={logo} title="Logo" />

<!-- Always inline (no sprite) -->
<Icon name="close" is:inline />

<!-- Accessible decorative icon -->
<Icon name="mdi:menu" class="size-5" aria-hidden="true" />

Task	What to do
Add a local icon	Drop a .svg file in src/icons/
Use an Iconify icon	Install @iconify-json/<set> then use name="set:icon"
Use in React/Vue/Svelte	Import from astro-iconset/react (or /vue, /svelte, etc.)
Change icon color	Add class="text-blue-500" or color CSS — needs currentColor in SVG
Change icon size	Add size={24} or width/height props
Fix TypeScript error on ?icon	Add /// <reference types="astro-iconset/svg-icon" /> to src/env.d.ts
Shrink SSR bundle	Add include: { mdi: ["…"] } to integration options

Updating Astro Iconset

Third-party integrations are not handled by @astrojs/upgrade. Install the latest tag manually:

npm

npm install astro-iconset@latest

pnpm

pnpm add astro-iconset@latest

Yarn

yarn add astro-iconset@latest

See the changelog for release notes.

Troubleshooting

See the Troubleshooting guide for solutions to common errors: icon not found, wrong size or color, TypeScript ?icon errors, and SSR bundle issues. For Astro itself, start with the Astro documentation. For bugs and feature requests, use GitHub issues.