Components

Astro Icon’s main API is an Icon component that automatically inlines an <svg> directly in your markup.

Icon

You can use the Icon component by importing it from astro-icon/components and rendering it as a normal Astro Component.

---
import { Icon } from 'astro-icon/components'
---

<!-- Embed the contents of the `/src/icons/logo.svg` file -->
<Icon name="logo" />

Because astro-icon is powered by Astro, this component only renders on the server to static HTML. It has no runtime footprint.

Props

The Icon component accepts the following properties:

interface Props extends HTMLAttributes<"svg"> {
  /** The name of the icon to include */
  name: string;
  /** Shorthand for including a <title>{props.title}</title> element in the SVG */
  title?: string;
  /** Shorthand for including a <desc>{props.desc}</desc> element in the SVG */
  desc?: string;
  /** Shorthand for setting width and height */
  size?: number | string;
  width?: number | string;
  height?: number | string;
}

The Icon also accepts any global HTML attributes and aria attributes. They will be forwarded to the rendered <svg> element.

Automatically optimized sprites

Because Astro controls the entire rendering lifecycle for a given Request, astro-icon is able to automatically optimize repeated references to the same icon on a page.

The approach uses a novel take on the more traditional SVG Sprite system that leverages a single <svg> sprite for your entire site. The first time the Icon component is included on a page, it defines a sprite <symbol> with a unique ID and immediately renders that symbol with the <use> element. If the same icon is referenced again, Icon will render only a <use> element, reducing the overall size of your HTML document by referencing the existing <symbol>.

---
import { Icon } from 'astro-icon/components'
---

<Icon name="logo" />
<!-- First usage generates the following HTML -->
<svg data-icon="logo">
  <symbol id="ai:uniqueid"><!-- contents of /src/icons/logo.svg --></symbol>
  <use href="#ai:uniqueid"></use>
</svg>

<Icon name="logo" />
<!-- Additional usage generates the following HTML -->
<svg data-icon="logo">
  <use href="#ai:uniqueid"></use>
</svg>

Usage with Framework Components

The <Icon /> component, like any other Astro component, cannot be used directly in UI framework components.

But, you can pass the static content generated by <Icon /> to a framework component inside a .astro file as children or using a named <slot/>:

---
import ReactComponent from './ReactComponent.jsx'
import { Icon } from "astro-icon/components"
---

<ReactComponent>
  <Icon name="logo" />
</ReactComponent>