astro-iconify-svgmap

astro-iconify-svgmap

Generates SVG sprite maps from Iconify icon packs at build time and serves them during dev. Icons are registered lazily via getIcon() and assembled into per-pack sprite files.

Setup

1. Install the integration and at least one @iconify-json/* pack:

pnpm add @stephansama/astro-iconify-svgmap @iconify-json/mdi

1. Add to astro.config.mjs:

import { createIntegration } from "@stephansama/astro-iconify-svgmap";
import { defineConfig } from "astro/config";

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

1. Import the virtual module in your base layout (this activates the Vite plugin):

---
// src/layouts/BaseLayout.astro
import "virtual:iconify-svgmap";
---

1. Use icons in any .astro component:

---
import { getIcon } from "@stephansama/astro-iconify-svgmap/get";

const iconHref = await getIcon("mdi", "home");
---

<svg width="24" height="24">
  <use href={iconHref}></use>
</svg>

Core Patterns

Basic icon rendering

---
import { getIcon } from "@stephansama/astro-iconify-svgmap/get";

const href = await getIcon("mdi", "account");
---

<svg width="24" height="24" aria-hidden="true">
  <use href={href}></use>
</svg>

getIcon(pack, name) returns /<pack>.svg#<name> — a fragment reference into the generated sprite. On the server it also registers the icon in the usage tracking file so the build step knows to include it in the sprite.

Monorepo setup with iconifyRootDirectory

// astro.config.mjs — inside a pnpm monorepo where icons are in the workspace root
import { createIntegration } from "@stephansama/astro-iconify-svgmap";
import { defineConfig } from "astro/config";

export default defineConfig({
  integrations: [
    createIntegration({
      iconifyRootDirectory: new URL("../../", import.meta.url),
    }),
  ],
});

iconifyRootDirectory is a URL pointing to the directory whose node_modules contains the @iconify-json/* packages. Defaults to the Astro project root.