SVG imports (?icon)

You can import a single .svg file as Iconify-compatible data using the ?icon query. That is useful when a file should not live in a shared icon directory, or you want to treat one asset as icon data explicitly.

Usage

Use either name (registry) or icon (imported data) — not both.

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

<Icon icon={logo} title="Site logo" />

TypeScript

The package ships type definitions for *.svg?icon imports. Add them using one of these two approaches:

Option A — src/env.d.ts (recommended for Astro projects):

src/env.d.ts

/// <reference types="astro/client" />
/// <reference types="astro-iconset/svg-icon" />

Option B — tsconfig.json types array:

tsconfig.json

{
  "compilerOptions": {
    "types": ["astro-iconset/svg-icon"]
  }
}

After adding the reference, restart your TypeScript server. Without this, imports like import logo from "../assets/logo.svg?icon" will show a “Cannot find module” error even though they work at build time.

If you still see the error after adding the reference, see Troubleshooting.

When to use ?icon vs name

Approach	Best for
name="slug"	Icons under your configured iconDir / iconDirs (shared registry)
icon={imported}	One-off files, assets in arbitrary folders, or comparing pipeline output to registry icons

For more on the Icon component, see Components.