SVG Icons in Astro — The Right Way
This is the big one. If you’re using React, Vue, Svelte,
Preact, or Solid islands in your Astro project — and most
real projects do — `astro-icon`’s `<Icon />` component simply
doesn’t work inside them. You’re stuck either avoiding islands
for anything icon-related or maintaining a separate icon
solution just for your island components.
## The Right Way — astro-iconset
I got frustrated enough that I built `astro-iconset` to solve
all three problems.
### Named Directory Prefixes
Instead of one flat `src/icons/` folder, you define named
directories with prefixes:
```js
// astro.config.mjs
import { defineConfig } from ‘astro/config’
import iconset from ‘astro-iconset’
export default defineConfig({
integrations: [
iconset({
iconDirs: [
{ prefix: ‘ui', dir: ‘src/icons/ui’ },
{ prefix: ‘brand', dir: ‘src/icons/brand’ },
{ prefix: ‘social', dir: ‘src/icons/social’ },
]
})
]
})If you’ve built anything with Astro, you’ve dealt with SVG icons.
And if you’ve dealt with SVG icons in Astro, you’ve probably hit
the same walls I did.
## The Problem with SVG Icons in Astro
The naive approach is dropping SVG files directly into your
components as inline code. It works — until you have 30 icons
across 20 components and the same SVG is inlined 15 times in
your HTML output. Your page weight balloons and there’s no
deduplication happening anywhere.
The next step most developers take is reaching for `astro-icon`.
It’s the go-to solution in the Astro ecosystem and it’s genuinely
good. You get Iconify support, automatic SVGO optimization, and
sprite deduplication out of the box.
But as your project grows, you start hitting its limits.
## Where astro-icon Falls Short
Here’s what I kept running into:
One shared directory for everything
astro-icon gives you `src/icons/` and that’s it. One folder.
As projects scale, dumping every icon — brand assets, UI icons,
social icons, generated Figma exports — into one flat directory
gets messy fast. There’s no clean way to organize by category
or source.
No way to import a one-off SVG
Sometimes you have a logo or a custom illustration that lives
next to the component that uses it. With astro-icon, you’re
forced to move it to the shared `src/icons/` directory just
to use it. That breaks the natural file colocation pattern
that makes Astro projects so clean.
Icons don't’work inside framework islands
