How to Add Icons to an Astro Site (Without Losing an Hour Per Icon)

Every site needs icons - navigation, feature lists, buttons, social links, empty states. And almost nobody has a workflow for them. You need one arrow, so you google “arrow icon svg”, open four tabs, compare sets that don’t match, download a file, clean up the markup, and twenty minutes are gone. Multiply by every icon on the site.

This guide covers the technical side first - the right way to put icons on an Astro site - and then the workflow side: how to find good icons fast enough that they stop being an interruption.

The three ways to add icons in Astro

Inline SVG: the right default

Astro renders to static HTML, and inline SVG is static markup - a perfect match. An inlined icon ships with the page, needs no request, scales crisply at any size, and picks up your text color automatically if you set fill="currentColor" or stroke="currentColor".

The cleanest pattern is one small component per icon:

---
interface Props {
  size?: number;
}
const { size = 20 } = Astro.props;
---

<svg
  xmlns="http://www.w3.org/2000/svg"
  width={size}
  height={size}
  viewBox="0 0 24 24"
  fill="none"
  stroke="currentColor"
  stroke-width="2"
  stroke-linecap="round"
  stroke-linejoin="round"
  aria-hidden="true"
>
  <path d="M5 12h14M12 5l7 7-7 7" />
</svg>

Then <ArrowRight size={16} /> anywhere you need it. The icon inherits the surrounding text color, so a hover state on the parent styles the icon for free.

Icon component packages

Packages like astro-icon give you thousands of icons behind one component: <Icon name="mdi:rocket" />. They resolve at build time, so the output is still inline SVG with no runtime cost. This is a fine approach - the tradeoffs are a dependency to keep updated and, more importantly, unlimited easy access to dozens of visually different sets, which quietly creates the consistency problem below.

Icon fonts: skip them

Font Awesome-style icon fonts load a whole font file on every page for the handful of glyphs you use, render soft at odd sizes, and fall apart when the font fails to load. They made sense a decade ago. On a static Astro site they are pure overhead.

The mistake that makes sites look off: mixed sets

The most common icon problem is not technical. It is a thin 1.5px-stroke arrow sitting next to a chunky filled bell from another set. Visitors can’t articulate it, but the page reads as unpolished.

The fix is one rule: pick one visual anchor and source everything through it. Same stroke width, same corner radius, same visual weight. If a set is missing an icon you need, take it from another set but adjust it to match - stroke, size, optical alignment - rather than pasting it in as-is.

Doing that adjustment by hand in an editor is exactly the kind of fiddly work that makes people give up and ship the mismatch.

A faster way to find and normalize icons

Full disclosure: Motificons is built by the same maker as AeroLaunch - it exists because of the workflow above. It collects over 300,000 icons from the open-source icon sets (every icon keeps its original license, shown next to it), and it solves the two slow parts:

Finding. Search across every set at once, filter by set or category, and see everything on one page instead of ten tabs.

Matching. Pick one icon as your visual reference and Motificons adjusts the stroke, size and color of every other icon you take - then hands you production-ready markup: plain SVG, or a ready component for React, Vue, Svelte or SwiftUI. For an Astro site, you copy the SVG straight into a component like the one above.

The Mac app: icons without leaving your editor

If you build sites daily, the bigger win is the Motificons Mac app. It works like Spotlight: press Ctrl-Option-Space in any app - VS Code, Figma, Photoshop, your browser - type what you need, hit Enter, and the icon is on your clipboard in the right format for wherever you’re pasting. Vector in design tools, PNG in Photoshop, code in your editor.

The entire library ships inside the app, so search is local and instant, and it works offline. The loop that used to cost twenty minutes - tabs, downloads, cleanup - becomes two seconds, and you never leave your file.

Icons for coding agents

One more piece, relevant if you build with Claude Code, Cursor or Codex: Motificons has an MCP server, so your agent can search icons by intent (“a quiet empty state”) instead of guessing filenames, pick only from the collection you curated for the project, and even audit a repo for off-system icons and orphan SVGs. You curate visually on the web; the agent consumes exactly that. If you generate sites with AI - as many AeroLaunch users do - this is how the icons stay on-system without you reviewing every choice.

The short version

• Inline SVG as small Astro components - no fonts, no runtime libraries.
• One visual anchor per site: same stroke, same weight, everywhere.
• Fix the workflow, not just the markup: Motificons makes finding and matching icons fast, and its Mac app turns the whole thing into one keystroke.

Icons stop being an errand. They become a keystroke - and your Astro site looks like one designer made every glyph.