SVG Icons in Astro: The Complete Guide (Zero-JS, Iconify and Component Islands)

Astro's whole promise is zero JavaScript by default, and SVG icons in Astro should honour that: an icon is markup, not a runtime. Here are the patterns that keep icons fast, from hand-inlined SVG to component islands.

Why icons are an architecture decision in Astro

In most frameworks the icon question is a bundle question. In Astro it is a rendering question. Every component ships as HTML unless you explicitly hydrate it, so an icon placed in an .astro file costs bytes in the document and nothing else, while the same icon inside a hydrated island drags a framework runtime behind it. That asymmetry is why experienced Astro teams are strict about icon placement: static SVG for everything static, framework icon packages only inside islands that were already interactive for other reasons. Internalise that split and the rest of this guide is detail. Ignore it, and you can lose Astro's entire performance advantage to a header search icon.

Pattern 1: inline the SVG (the zero-JS default)

For content sites, the fastest icon is the one pasted directly into your .astro template. It costs no requests, no hydration and no dependency, and Astro will not add a byte of JS for it. Keep a components/icons folder, one file per icon, with currentColor so themes apply. Copy production-ready markup for any icon from IconVault instead of hand-cleaning files.

A tidy Astro icon component takes props for size and class, spreads any extra attributes onto the svg, and defaults to decorative. Build five of these and you will reuse them for years:

---
// src/components/icons/SearchIcon.astro
const { size = 20, class: className = "" } = Astro.props;
---
<svg width={size} height={size} viewBox="0 0 24 24" fill="none"
     stroke="currentColor" stroke-width="2" class={className} aria-hidden="true">
  <circle cx="11" cy="11" r="7" />
  <path d="M21 21l-4.3-4.3" />
</svg>

Hand-inlining scales further than people expect. A blog or documentation site typically needs thirty to sixty distinct glyphs, each a few hundred bytes after compression, deduplicated by your component structure rather than repeated raw markup. The failure mode is not size; it is inconsistency, where icons pasted months apart arrive with different viewBoxes and stroke conventions. Source every glyph from one family, preview them together in that family's set page, and the folder stays coherent.

Pattern 2: astro-icon with local data packages

When a project needs hundreds of icons, astro-icon plus the @iconify-json data packages gives you name-based usage with build-time inlining: the icon becomes static SVG in the HTML, still zero client JS. This is the sweet spot for documentation sites and blogs that pull from several sets like Lucide and Simple Icons.

npm install astro-icon
npm install -D @iconify-json/lucide @iconify-json/simple-icons

---
import { Icon } from "astro-icon/components";
---
<Icon name="lucide:search" size={20} />
<Icon name="simple-icons:github" size={20} />

Under the hood, astro-icon resolves the name against locally installed data at build time and inlines the resulting SVG, so the runtime story stays exactly as strict as hand-inlining. You can also drop raw SVG files into src/icons and reference them by filename, which is the cleanest way to include a logo or a one-off illustration glyph in the same syntax. Two operational notes matter. First, a missing data package fails the build loudly rather than the page silently, which is the behaviour you want. Second, because resolution happens per usage, using an icon in fifty places inlines it fifty times unless it flows through a shared component; for a glyph repeated across every page, such as a logo or a chevron, weigh the sprite pattern below.

Pattern 3: icons inside framework islands

If part of the page is a React, Vue or Svelte island, use that framework's icon package inside the island (lucide-react, lucide-vue-next and friends) and static SVG everywhere else. Do not hydrate a whole island just to render a search icon in the header: that is the most common way Astro sites quietly lose their performance edge. Our guide to optimizing SVG icons for faster sites covers the measurement side.

The subtle trap is the shared header. Marketing pages often put a framework-powered menu or search box in the header, and developers then reach for the framework's icons everywhere on the page for consistency. Resist the shortcut. The island can import its own icons internally, while the surrounding .astro layout uses the same family's static SVG, visually identical because it is the same artwork. The user sees one system; the network sees one small island instead of a page-wide runtime. If an island is deferred with client:visible or client:idle, its icons arrive with it, which is one more reason interactive chrome should be self-contained.

Pattern 4: SVG sprites for repeated glyphs

When the same icons repeat many times per page, think of a feed with fifty like buttons or a docs sidebar with per-item glyphs, a sprite can beat inlining. Define each glyph once as a symbol in a hidden SVG, then instantiate it anywhere with a use element. The definitions can live in your base layout, and every instance inherits currentColor theming from its context.

<svg width="0" height="0" style="position:absolute" aria-hidden="true">
  <symbol id="i-heart" viewBox="0 0 24 24">
    <path d="M19 14c1.49-1.46 3-3.21 3-5.5A5.5 5.5 0 0 0 16.5 3c-1.76 0-3 .5-4.5 2-1.5-1.5-2.74-2-4.5-2A5.5 5.5 0 0 0 2 8.5c0 2.3 1.5 4.05 3 5.5l7 7Z" />
  </symbol>
</svg>

<svg width="20" height="20" fill="currentColor" aria-hidden="true">
  <use href="#i-heart" />
</svg>

Sprites have real costs: the symbol artwork cannot be styled per instance beyond inherited properties, multi-colour icons do not belong in them, and an external sprite file reintroduces a request and caching questions. For most Astro sites, component-based inlining plus gzip or brotli compression, which crushes repeated SVG markup efficiently, is simpler and nearly as light. Reach for the sprite when repetition is extreme or when you need icons inside user-generated content where components cannot go. The sprite generator assembles a clean sprite from individual files if you go this route.

Pattern 5: CSS masks for single-colour glyphs

One more zero-JS technique deserves a place in the toolbox: CSS mask-image with an SVG data URI. The element gets background: currentColor and the mask supplies the shape, which makes hover and theme colour changes pure CSS with no extra markup. It suits small monochrome marks in navigation and footers. The trade-offs are real: the data URI must be URL-encoded correctly, the icon cannot be reached by assistive technology so it is decorative-only by construction, and multi-path colour icons are out. Generate encoded URIs with the SVG to data URI tool rather than hand-encoding, which is error-prone in exactly the characters SVG uses most.

Icons in MDX and content collections

Astro blogs and docs usually meet icons inside MDX, where authors want a callout glyph or an inline mark inside prose. Because MDX compiles to components, both hand-made .astro icon components and astro-icon work inside content, passed through the components mapping when you render the entry. Keep the vocabulary tiny and documented for authors: a callout set (info, warning, danger, tip) and a handful of inline marks covers real usage. For icons generated from frontmatter, such as a per-post category glyph, resolve the name in the template with astro-icon rather than storing markup in content files, so the content stays portable and the artwork stays in the icon layer where it belongs.

Astro icon rules

• Static content gets static SVG. Islands get framework components. Never mix the two in one component.
• Set width and height (or an aspect-ratio) on every icon to prevent layout shift.
• Use currentColor and CSS variables for theming; avoid per-icon fill attributes.
• For icon fonts: do not. They break the zero-JS, zero-FOUT story Astro is built on.

Theming and dark mode without JavaScript

Static SVG themes beautifully with plain CSS, which is the point of the exercise. Drive colour through color and currentColor, scope brand exceptions with utility classes, and let a class-based or media-query dark mode flip variables while icons follow untouched. Where a design needs a softer icon tone than body text, set an explicit colour token for icon contexts, such as navigation and metadata rows, instead of opacity tricks on the svg, because opacity also fades the glyph's edges against busy backgrounds. None of this needs a theme script, and avoiding one keeps the critical rendering path exactly as empty as Astro promises.

Accessibility for inlined icons

Inlined SVG is markup, so it must behave like markup. Decorative glyphs get aria-hidden="true", and because inline SVG can receive focus in some older browsers when interactive, keep focusable off links' inner svg by putting interactive semantics on the link itself. An icon that is the only content of a link or button gives that element its accessible name problem to solve: add an aria-label to the control or visually hidden text inside it. Where an icon conveys information in content, such as a warning mark in a callout, pair it with text that carries the same meaning. The full checklist is in our accessible SVG icons guide.

Performance: measuring what icons cost in Astro

Icon weight in Astro shows up as HTML weight, and HTML compresses extremely well when it is repetitive. Before optimising, measure the built page: check the transferred size of a representative page, count inline svg elements, and look for accidental duplicates, such as the same glyph inlined by two different components that should have shared one. The usual findings are mundane: an unoptimised designer export with editor metadata still in it, a logo pasted at full illustration complexity, or an island that quietly hydrated a whole page section. Run suspect artwork through the SVG optimizer and re-check. In a healthy Astro build, total icon markup is a rounding error next to fonts and images, which is the outcome the patterns above are designed to produce.

Common errors and fixes

Icon name not found at build time

astro-icon resolves names against installed @iconify-json packages and your local src/icons folder. A not-found error means the set's data package is missing, the prefix is wrong, or the glyph name uses the set's internal naming rather than the display name. Install the package, then verify the exact identifier in the set's listing on the browse page before changing code.

The icon renders at a huge size

An inlined SVG without width and height, or with only a viewBox, expands to fill its container in some contexts. Always pass an explicit size through props or CSS. If a whole page of icons ballooned after a refactor, a shared component lost its default size prop; fix it there once rather than patching call sites.

A framework icon package bloated the island

Inside React or Vue islands, the rules from those ecosystems apply with full force: import icons by name, never through a barrel that pulls the set, and check whether the island imports an icon registry for a picker that most visitors never open. Lazy-load genuinely optional icon-heavy UI behind the interaction that needs it, using the framework's dynamic import support inside the island.

The sprite instance shows nothing

When a use reference renders blank, suspect the symbol definition: the sprite block must be present in the same document, the id must match exactly, and the symbol needs its own viewBox. Also check that a global CSS rule is not hiding svg elements with zero dimensions in a way that catches your instances. Test by temporarily giving the instance a background colour; if the box appears, geometry is fine and the reference is the problem.

Migrating an Astro site from icon fonts

Older Astro templates sometimes arrive with Font Awesome or a similar font loaded from a CDN, which quietly contradicts everything Astro is for: a render-blocking stylesheet, a font download, and glyph swap on load. Migration is mechanical. Inventory the icon classes in use, map each to the same-named glyph from your chosen family, replace the markup with components or astro-icon usages, and delete the font links. Expect the layout to get calmer, since font glyphs carry unpredictable line-box behaviour that SVG does not. Do the swap in one pass per layout region so no page ships half font and half SVG, and keep the mapping table with the change for the next maintainer.

Handled this way, SVG icons in Astro are effectively free: a few hundred bytes of HTML, cached with the page, rendered before first paint. Browse the sets you can draw from in the IconVault collections directory.

Organising a local icons folder that stays tidy

Local icon folders decay in predictable ways: inconsistent file names, three sizes of the same glyph, artwork from a second set sneaking in during a deadline. Prevent it with three conventions. Name files after the glyph, not the place it is used, so search stays meaningful. Keep a short readme in the folder stating the source set, the grid and the stroke rules every file must follow. And review new additions at the size they will ship, because a glyph that looks fine at 48px in a pull request screenshot can be mush at 18px in the sidebar. These habits cost minutes and save the folder from becoming the place icons go to be forgotten.

Brand and social icons at scale

Content sites lean on brand icons more than product apps do: author socials, share rows, footer links, integration logos on a landing page. Simple Icons through astro-icon handles this cleanly with original brand colours, still inlined at build time. Two practices keep it professional. Use the official artwork untouched rather than forcing logos into your interface set's style, because brand guidelines and user recognition both depend on accuracy. And give icon-only social links real accessible names, since 'our community links' rendered as four anonymous glyphs is the most common accessibility failure on marketing pages. Where a share action needs a count or a label anyway, prefer visible text next to the glyph; it converts better and reads better, and the icon becomes the decoration it should be.

Favicons and touch icons in Astro

Astro sites serve favicons as static files from the public directory, referenced in the base layout's head. An SVG favicon is the right default in 2026: one file, crisp at every size, and able to carry a dark-mode variant through a media query inside the SVG itself. Keep the design to a bold single shape, test it at 16px in a real browser tab, and provide the PNG and apple-touch-icon fallbacks from the same source artwork using the favicon generator. Because the layout is shared, this is a five-minute, whole-site improvement, and it is also the file most likely to be screenshotted when someone bookmarks you, which argues for doing it deliberately rather than inheriting a template placeholder.

View transitions and persisted icon elements

Astro's view transitions animate between pages without full reloads, and static SVG rides along without any special handling: it is DOM, and the transition treats it like any other element. The icon-relevant detail is persistence. If a header containing icons uses transition:persist, for example around a media player or a persistent navigation, the persisted subtree keeps its original DOM, so an icon theme change driven by a page-level class may not re-apply the way a fresh render would. Keep theming on variables that live above the persisted element, and icons will follow the rest of the interface. None of this requires JavaScript from the icons themselves, which remains the architectural point of every pattern in this guide.

Testing and visual checks for static icons

Static output is testable output. Your icon QA can be embarrassingly simple: build the site, then check the generated HTML for the pages that matter. Grep the dist output for svg counts on key templates to catch a component that silently stopped rendering, screenshot the icon-dense pages in your preview pipeline, and click through social and navigation links with a keyboard to feel whether focus states survive around inlined glyphs. Because nothing about the icons changes at runtime, a defect found in the build is the defect every visitor would have seen, and a clean build is genuinely reassuring. Teams coming from runtime icon systems often over-test here out of habit; redirect that energy to the islands, where hydration gives icons a second life that can actually diverge.

The Astro icon checklist

• Every static surface uses static SVG, through local components or astro-icon, with zero icon JavaScript.
• Framework icon packages appear only inside islands that are interactive for other reasons.
• Each icon carries an explicit size, and repeated glyphs flow through shared components rather than pasted markup.
• One source family per job: interface glyphs from one set, brand marks as official artwork.
• Decorative icons are aria-hidden, icon-only controls are labelled, and informational icons are paired with text.
• Designer exports are optimised before they enter the repo, and favicons ship as SVG with generated fallbacks.

Choosing a pattern per page type

Let the page type choose the pattern. A marketing homepage, a documentation site and a blog have different icon needs, and Astro SVG icons should follow the page rather than a single house rule. Marketing pages want a handful of large, expressive glyphs that can be inlined once and reused; documentation sites want hundreds of small, consistent interface glyphs best served by a local data package; blogs usually need almost nothing beyond social and share marks. When teams plan how to use SVG icons in Astro, mapping patterns to page types first prevents the common mistake of installing a heavy icon system for a site that needed twelve glyphs. Astro SVG icons chosen per page stay proportional to the site they serve.

Count glyphs before choosing machinery. The most reliable scoping question for Astro SVG icons is simply how many distinct icons the finished site will contain, because that number decides everything downstream. Under thirty, inline components in a shared folder are unbeatable: zero dependencies, zero build plugins, full control. Between thirty and a few hundred, a local data package with an Icon component earns its place by removing duplication. Above that, or across many sets, a sprite or a build-time import system starts to pay off. Guidance on how to use SVG icons in Astro should therefore open with a count, not a package recommendation, since Astro SVG icons at the wrong scale cost either maintenance or bytes for no benefit.

Icons in layouts and components

Props make icons reusable without islands. In Astro components, Astro SVG icons work best as props: a Card component accepts an icon name and renders it from the shared Icon component, so content authors never touch SVG markup. The prop contract should be small, name plus size plus an optional class, and the component should resolve the name against a curated map rather than accepting arbitrary identifiers, which keeps the rendered set predictable. When documenting how to use SVG icons in Astro layouts, the prop pattern deserves emphasis, because it is what lets a layout stay zero-JavaScript while still varying its iconography per page. Astro SVG icons passed as props are data, not code, and data is easier to audit.

Slots handle the cases props cannot. Sometimes an icon needs custom positioning, a wrapper element or a companion label that a name prop cannot express, and Astro slots solve this cleanly: the caller passes full markup into a named slot and the layout places it. The rule of thumb is props for standard glyphs and slots for exceptional compositions, with the exceptional cases kept rare enough to review individually. Teams standardising how to use SVG icons in Astro should write this rule down, because without it every caller invents a slightly different composition and the layout's visual rhythm erodes. Astro SVG icons through slots stay flexible without surrendering consistency, as long as the slot contract is documented beside the layout.

Icons in content collections and MDX

Frontmatter can carry icon names safely. Content collections let authors declare an icon per entry, such as a feature or a team member, and Astro SVG icons render from that frontmatter through the same curated map used by layouts. The schema should validate the icon field against the allowed list at build time, so a typo fails the build with a clear message instead of rendering an empty box in production. When explaining how to use SVG icons in Astro content, the schema validation step is the part most guides skip and most sites need, because content authors are not developers and should never debug a silent icon failure. Astro SVG icons from validated frontmatter are content, and content with a schema is content that scales.

MDX components beat raw SVG in prose. Inside MDX articles, authors should invoke an Icon component by name rather than pasting SVG markup, because pasted markup drifts, bloats the article and breaks when the design system changes. Register the Icon component for MDX once, document the allowed names beside the authoring guide, and let writers focus on words while the component guarantees size, colour and accessibility defaults. For teams publishing how to use SVG icons in Astro for documentation sites, the MDX pattern is the difference between a docs site that stays consistent for years and one that accumulates a different icon style per article. Astro SVG icons in prose should be as boring and reliable as the headings around them.

Dark mode and theming for static icons

Static sites theme icons with CSS, not JavaScript. Astro SVG icons inherit currentColor, so a site that toggles dark mode through a class on the document element needs no icon-specific JavaScript at all: the same CSS variables that recolour text recolour glyphs. The trap is a hard-coded fill inside an exported SVG, which ignores the theme and glows wrong in dark mode, so every icon source should be audited for fixed colours before it enters the shared folder. When writing about how to use SVG icons in Astro with theming, the audit step belongs in the guide, because static sites have no runtime to paper over a bad fill. Astro SVG icons themed through variables are free; themed through per-icon overrides, they are a maintenance burden.

Semantic colours deserve tokens in static sites too. Success, warning and error states on a static site still need consistent hues, and those hues should come from design tokens rather than from an author's memory of a hex value. Define the tokens once in the global stylesheet, consume them through utility classes on the icon component, and verify contrast in both themes with a screenshot pass. Teams that treat how to use SVG icons in Astro as a token problem find that a rebrand touches one file instead of every page, which is precisely the leverage static sites are supposed to provide. Astro SVG icons in semantic roles should also never rely on colour alone: pair the hue with a distinct shape or a text label, so the meaning survives monochrome printing and colour vision differences.

Icons with Tailwind in Astro

Tailwind utilities are the natural sizing language. In an Astro plus Tailwind project, Astro SVG icons take their size from utility classes such as h-4 w-4 applied to the icon component, and the component must forward class to the rendered svg for this to work. The convention to document is a size scale mapped to roles: 16px for inline text icons, 20px for navigation, 24px for section headers, with larger display sizes reserved for feature graphics. When guides cover how to use SVG icons in Astro with Tailwind, they should stress class forwarding, because a component that swallows class is the most common reason utilities appear to fail. Astro SVG icons sized by utilities stay consistent with the spacing and typography scales around them, which is the whole point of a utility system.

Dark variants compose without extra work. Tailwind's dark variant recolours text and therefore recolours Astro SVG icons automatically when they use currentColor, so a dark-mode icon strategy in Astro is usually just the existing text colour strategy applied consistently. The exceptions to check are icons inside components with their own background, such as cards or callouts, where the icon should inherit the card's foreground token rather than the page's. For teams documenting how to use SVG icons in Astro with Tailwind, a short section on these nested contexts prevents the most common dark-mode icon bug, which is a glyph that is technically themed but practically invisible against its container. Astro SVG icons in Tailwind projects reward the same discipline as every other utility: consistent tokens, no one-off values.

Optimising icon SVG at build time

Optimise at build time, not by hand. Designer exports and library SVGs arrive with metadata, decimal-heavy paths and redundant groups, and Astro SVG icons should be cleaned by a build step rather than by developers editing path data. An SVGO pass in the build, or a pre-commit optimisation of the shared icon folder, typically shrinks glyphs substantially and removes the fixed width and height attributes that fight utility sizing. When explaining how to use SVG icons in Astro efficiently, the optimisation step should be presented as infrastructure, configured once and forgotten, rather than as a chore repeated per icon. Astro SVG icons optimised at build time stay small without anyone remembering to optimise them.

Measure the icon payload per page. Astro's zero-JavaScript promise concerns scripts, but icon markup still travels in HTML, and a page that inlines the same large glyph twenty times pays for it in bytes. The check is simple: build the site, inspect the largest pages, and count icon markup repetition; where one glyph repeats heavily, a sprite or a shared symbol definition earns its place. Teams that take how to use SVG icons in Astro seriously should add this check to their performance routine, because icon bytes are invisible in a Lighthouse JavaScript audit and easy to miss. Astro SVG icons measured per page stay honest about their cost, and honest costs are what keep static sites fast.

Icons inside framework islands

Islands should reuse the static icon contract. When an Astro page hydrates a React, Vue or Svelte island, Astro SVG icons inside that island come from the island's own icon package, and the risk is a second visual system appearing inside an otherwise consistent page. The fix is a shared decision: either the island renders icons from the same family and size scale as the static shell, or the island accepts icons as props from the Astro parent, which renders them statically and passes them in. When documenting how to use SVG icons in Astro with islands, the prop-passing pattern deserves a worked example, because it is the only approach that keeps the island's iconography identical to the shell's without duplicating the set. Astro SVG icons that cross the island boundary through props are the most reliable kind.

Keep island icon JavaScript minimal. An island that imports a full icon library for two glyphs defeats Astro's partial hydration story, so island components should import icons by name from a tree-shakeable package, exactly as a standalone app would. Audit island bundles with the same discipline as page scripts, and prefer passing static SVG from the Astro parent whenever the glyph never changes after hydration. For teams scaling how to use SVG icons in Astro with many islands, this audit is what prevents the slow creep of duplicated icon code into every hydrated component. Astro SVG icons in islands should cost the same as Astro SVG icons anywhere else: exactly the glyphs used, nothing more.

Accessibility for static iconography

Static does not mean automatically accessible. Astro SVG icons that are purely decorative must carry aria-hidden, and icon-only links and buttons need accessible names, just as in any framework; the static nature of the site changes nothing about these requirements. The advantage Astro offers is that these attributes can be baked into the shared Icon component once, so every usage inherits correct behaviour without author intervention. When guides describe how to use SVG icons in Astro accessibly, the shared component is the hero of the story, because it turns accessibility from a per-usage reminder into a default. Astro SVG icons through a component with aria-hidden by default and a label prop for meaningful cases are accessible by construction.

Test the rendered HTML, not the source. Because Astro renders at build time, the accessibility check that matters is the built HTML: view source on a representative page and confirm decorative glyphs are hidden and icon-only controls are labelled. Add this check to the build review for icon-heavy templates, and consider an automated HTML audit that flags svg elements without aria-hidden or a title where a label is expected. For teams finalising how to use SVG icons in Astro, a built-HTML check catches the failures that source review misses, such as a component that renders correctly in isolation but loses its label when composed inside a link. Astro SVG icons verified in output HTML are verified where users actually meet them.

Growing the icon system as the site grows

Start small and let the system earn complexity. The healthiest Astro SVG icons trajectory starts with inline components, graduates to a data package when the count justifies it, and adopts sprites or build-time imports only when repetition is measured. Each graduation should be a deliberate pull request with a reason, not a fashion-driven rewrite, because every layer of machinery is a layer someone must maintain. When advising how to use SVG icons in Astro for a growing site, the graduation ladder is more useful than any single recommendation, since it tells a team not just what to use now but when to change. Astro SVG icons that grow by measured steps never carry machinery the site has not yet earned.

Document the current rung of the ladder. Wherever the system sits today, a short document stating the approach, the allowed sets, the size scale and the migration path to the next rung saves every future contributor from guessing. Update that document in the same pull request as any icon change, and review it when the glyph count crosses a threshold, such as fifty or two hundred, since thresholds are the honest trigger for graduation. Teams that maintain how to use SVG icons in Astro as living documentation find that onboarding a new contributor takes minutes rather than days. Astro SVG icons with a written system outlast the people who built them, which is the truest test of any engineering choice.

Responsive sizing for static icons

Static pages still need a responsive icon plan. For Astro SVG icons, the glyph should stay constant while the layout adapts around it, and Astro SVG icons that change size per breakpoint make a site feel different on every device. Teams planning how to use SVG icons in Astro responsively should size icons by role rather than by screen, because Astro SVG icons sized by role stay consistent from phone to desktop. The advice on how to use SVG icons in Astro at responsive scale is to check the smallest viewport first, since Astro SVG icons that work at 360px work everywhere else.

Collapse toolbars instead of shrinking glyphs. For Astro SVG icons, shrinking below 16px on small screens trades legibility for completeness, and Astro SVG icons hidden behind a menu preserve both. Teams designing how to use SVG icons in Astro for mobile should define a collapse order per toolbar, because Astro SVG icons without a plan overflow or crowd. The practice for how to use SVG icons in Astro on small screens is a documented order, so Astro SVG icons degrade predictably instead of breaking the layout.

Directional icons and RTL for static sites

Mirror arrows when the page direction flips. For Astro SVG icons, directional glyphs such as back, forward and chevrons must mirror in right-to-left layouts, and Astro SVG icons that ignore direction confuse readers who scan right to left. Teams implementing how to use SVG icons in Astro internationally should use logical CSS properties that flip automatically, because Astro SVG icons handled with manual overrides rot with every redesign. The standard for how to use SVG icons in Astro across locales is a documented list of directional glyphs, so Astro SVG icons mirror exactly where they should.

Check RTL in the built HTML. For Astro SVG icons, the verification that matters is the built page in an RTL locale, navigated end to end, and Astro SVG icons that fail there are cheap to fix before release. Teams testing how to use SVG icons in Astro globally should add one RTL page to their visual checks, because Astro SVG icons in mirrored layouts are easy to verify and embarrassing to miss. The discipline for how to use SVG icons in Astro at global scale is a locale pass before launch, so Astro SVG icons never become an afterthought.

Icons in Starlight and documentation themes

Docs themes bring their own icon conventions. For Astro SVG icons, a Starlight-based documentation site already ships its own iconography for callouts, navigation and search, and Astro SVG icons added by authors should match that existing language rather than introducing a second family. Teams learning how to use SVG icons in Astro for documentation should first inventory what the theme already provides, because Astro SVG icons that duplicate theme glyphs create visual noise. The guidance on how to use SVG icons in Astro docs is to extend the theme's set sparingly, so Astro SVG icons feel native to the docs rather than pasted on.

Custom docs glyphs belong in one override file. For Astro SVG icons, any glyph beyond the theme's set should live in a single documented override location, and Astro SVG icons added anywhere else scatter across the docs and drift. Teams managing how to use SVG icons in Astro documentation should review custom glyphs with the same care as content changes, because Astro SVG icons in docs are seen by every reader. The rule for how to use SVG icons in Astro docs sites is one override file and one reviewer, so Astro SVG icons stay as consistent as the prose around them.

A request process for new static-site icons

Route new glyphs through a short request. For Astro SVG icons, a template asking for the meaning, the page and the nearest existing glyph prevents most duplicates, and Astro SVG icons added through requests stay inside the documented family. Teams formalising how to use SVG icons in Astro at scale should review requests alongside content changes, because Astro SVG icons requested during a campaign are how second families enter a site. The habit for how to use SVG icons in Astro in growing teams is periodic request review, so Astro SVG icons grow deliberately rather than accidentally.

Answer requests with the existing set first. For Astro SVG icons, the most common outcome is discovering the set already covers the need, and Astro SVG icons found this way cost nothing and keep the system intact. Teams stewarding how to use SVG icons in Astro should reply with a screenshot of the closest existing glyph at production size, because Astro SVG icons judged at poster size mislead requesters. The principle for how to use SVG icons in Astro over years is slow, deliberate growth, so Astro SVG icons added today still belong to the same family tomorrow.

Onboarding contributors onto the icon system

Teach the shared component before the first page. For Astro SVG icons, a new contributor's first lesson should be the Icon component, the size scale and the curated name map, and Astro SVG icons explained through the component become a system rather than scattered markup. Teams onboarding around how to use SVG icons in Astro should put icon conventions in the contributor guide, because Astro SVG icons are often the first thing a new author touches. The guidance for how to use SVG icons in Astro in contributor teams is that conventions taught early are conventions kept, so Astro SVG icons stay consistent through turnover.

Review the first icon change as teaching. For Astro SVG icons, a contributor's first glyph addition, reviewed against the checklist, teaches more than any document, and Astro SVG icons handled in a reviewed first change set the standard for everything after. Teams practising how to use SVG icons in Astro with new contributors should treat that review as teaching, because Astro SVG icons reviewed early prevent habits that audits later punish. The rule for how to use SVG icons in Astro at community scale is that every contributor's first icon change is reviewed, so Astro SVG icons remain a shared standard.

Frequently asked questions

Does astro-icon add any JavaScript to the page?

No. astro-icon resolves icon names at build time against locally installed data packages and inlines the resulting SVG into the HTML. There is no client runtime, no fetch and no hydration involved. If a page using astro-icon ships JavaScript, it came from an island or another integration, not from the icons.

Should I inline icons or use an SVG sprite in Astro?

Inline by default. Component-based inlining is simpler, themes with currentColor, and compresses well because HTML transfers with gzip or brotli. Use a sprite when the same glyph repeats dozens of times on one page or must appear inside content where components cannot be used. Avoid external sprite files, which reintroduce requests and caching complexity.

Can I use lucide-react for icons in an Astro site?

Yes, but only inside React islands, where it behaves exactly as it does in a React app. For the static parts of the page, use the same Lucide artwork as inline SVG through astro-icon or local components. Mixing the two sources is safe because the artwork and grid are identical; what you must avoid is hydrating an island solely to render icons.

Why does my icon change size between pages?

Inconsistent sizing comes from missing width and height on some instances or from a global CSS rule that scales svg elements in prose. Fix it at the component layer: give every icon component a default size prop, and scope any prose-specific svg rules so they cannot leak into components. Consistency at 16, 20 and 24px covers nearly all real layouts.

Are icon fonts ever acceptable in Astro?

Practically, no. An icon font adds a stylesheet and a font file to the critical path, swaps glyphs in after load, and announces meaningless characters to assistive technology. Every icon font glyph exists as SVG in the same family, and the patterns in this guide render that SVG with zero JavaScript, so the font has no remaining advantage.