# Icon

**`sonic-icon`** renders inline SVG icons from the **bundled core set** or from **CDN libraries**. Set **`name`** (and **`library`** / **`prefix`** when needed); scale with **`size`**. Icons inherit **`currentColor`** and are **`aria-hidden`** by default—keep visible text nearby or label the control that contains them.

## Core library

Omit **`library`** to use the bundled set in `icons.json`. Available **`name`** values: `cancel` · `check` · `check-circled-outline` · `emoji-puzzled` · `info-empty` · `loader` · `minus-small` · `more-horiz` · `more-vert` · `nav-arrow-down` · `warning-circled-outline`.

<sonic-code>
  <template>
    <div class="grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-4 gap-8">
      <div class="text-center">
        <sonic-icon name="cancel" size="lg"></sonic-icon>
        <div class="text-xs mt-1">cancel</div>
      </div>
      <div class="text-center">
        <sonic-icon name="check" size="lg"></sonic-icon>
        <div class="text-xs mt-1">check</div>
      </div>
      <div class="text-center">
        <sonic-icon name="check-circled-outline" size="lg"></sonic-icon>
        <div class="text-xs mt-1">check-circled-outline</div>
      </div>
      <div class="text-center">
        <sonic-icon name="emoji-puzzled" size="lg"></sonic-icon>
        <div class="text-xs mt-1">emoji-puzzled</div>
      </div>
      <div class="text-center">
        <sonic-icon name="info-empty" size="lg"></sonic-icon>
        <div class="text-xs mt-1">info-empty</div>
      </div>
      <div class="text-center">
        <sonic-icon name="loader" size="lg"></sonic-icon>
        <div class="text-xs mt-1">loader</div>
      </div>
      <div class="text-center">
        <sonic-icon name="minus-small" size="lg"></sonic-icon>
        <div class="text-xs mt-1">minus-small</div>
      </div>
      <div class="text-center">
        <sonic-icon name="more-horiz" size="lg"></sonic-icon>
        <div class="text-xs mt-1">more-horiz</div>
      </div>
      <div class="text-center">
        <sonic-icon name="more-vert" size="lg"></sonic-icon>
        <div class="text-xs mt-1">more-vert</div>
      </div>
      <div class="text-center">
        <sonic-icon name="nav-arrow-down" size="lg"></sonic-icon>
        <div class="text-xs mt-1">nav-arrow-down</div>
      </div>
      <div class="text-center">
        <sonic-icon name="warning-circled-outline" size="lg"></sonic-icon>
        <div class="text-xs mt-1">warning-circled-outline</div>
      </div>
    </div>
  </template>
</sonic-code>

## External libraries

Set **`library`** to load SVGs from a built-in CDN template. **`prefix`** falls back to each library’s default when omitted (`outline` for **`heroicons`**, **`regular`** for **`fontAwesome`** and **`material`**, and so on).

<sonic-code>
  <template>
    <div class="grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-4 gap-8">
      <sonic-link href="https://heroicons.com/" target="_blank" class="text-center underline">
        <sonic-icon library="heroicons" prefix="outline" name="academic-cap" size="lg"></sonic-icon>
        <br />
        <div class="text-xs mt-1">heroicons</div>
      </sonic-link>
      <sonic-link href="https://iconoir.com/" target="_blank" class="text-center underline">
        <sonic-icon library="iconoir" name="2x2-cell" size="lg"></sonic-icon>
        <br />
        <div class="text-xs mt-1">iconoir</div>
      </sonic-link>
      <sonic-link href="https://materialdesignicons.com/" target="_blank" class="text-center underline">
        <sonic-icon library="material" prefix="outline" name="email" size="lg"></sonic-icon>
        <br />
        <div class="text-xs mt-1">material design</div>
      </sonic-link>
      <sonic-link href="https://fontawesome.com/search?o=r&m=free&s=regular" target="_blank" class="text-center underline">
        <sonic-icon library="fontAwesome" prefix="regular" name="user" size="lg"></sonic-icon>
        <br />
        <div class="text-xs mt-1">fontAwesome regular</div>
      </sonic-link>
      <sonic-link href="https://fontawesome.com/search?o=r&m=free&s=solid" target="_blank" class="text-center underline">
        <sonic-icon library="fontAwesome" prefix="solid" name="book" size="lg"></sonic-icon>
        <br />
        <div class="text-xs mt-1">fontAwesome solid</div>
      </sonic-link>
      <sonic-link href="https://feathericons.com/" target="_blank" class="text-center underline">
        <sonic-icon library="feathers" name="activity" size="lg"></sonic-icon>
        <br />
        <div class="text-xs mt-1">feathers</div>
      </sonic-link>
      <sonic-link href="https://lucide.dev/" target="_blank" class="text-center underline">
        <sonic-icon library="lucide" name="album" size="lg"></sonic-icon>
        <br />
        <div class="text-xs mt-1">lucide</div>
      </sonic-link>
    </div>
  </template>
</sonic-code>

## Custom library

Use **`library="custom"`** with SVG files on your origin. On an ancestor (for example **`sonic-scope`** or **`sonic-code`**), set **`customIconLibraryPath`** to a URL template with **`$prefix`** and **`$name`** placeholders, and optionally **`customIconDefaultPrefix`** when **`prefix`** is omitted.

<sonic-code
  customIconLibraryPath="/svg/$prefix/$name.svg"
  customIconDefaultPrefix="regular"
>
  <template>
    <sonic-scope
      customIconLibraryPath="/svg/$prefix/$name.svg"
      customIconDefaultPrefix="regular"
    >
      <div class="grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-4 gap-8">
        <div class="text-center">
          <sonic-icon library="custom" prefix="regular" name="plane"></sonic-icon>
          <br />
          <div class="text-xs mt-1">regular</div>
        </div>
        <div class="text-center">
          <sonic-icon library="custom" prefix="solid" name="plane"></sonic-icon>
          <br />
          <div class="text-xs mt-1">solid</div>
        </div>
        <div class="text-center">
          <sonic-icon library="custom" name="plane"></sonic-icon>
          <br />
          <div class="text-xs mt-1">default prefix</div>
        </div>
      </div>
    </sonic-scope>
  </template>
</sonic-code>

## Size

Omit **`size`** for the default scale (`1em` height, inherited from the font size). Steps go from `2xs` to `3xl`.

<sonic-code>
  <template>
    <div class="grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-4 gap-8">
      <div class="text-center">
        <sonic-icon library="heroicons" prefix="outline" name="academic-cap" size="2xs"></sonic-icon>
        <br />
        <div class="text-xs mt-1">2xs</div>
      </div>
      <div class="text-center">
        <sonic-icon library="heroicons" prefix="outline" name="academic-cap" size="xs"></sonic-icon>
        <br />
        <div class="text-xs mt-1">xs</div>
      </div>
      <div class="text-center">
        <sonic-icon library="heroicons" prefix="outline" name="academic-cap" size="sm"></sonic-icon>
        <br />
        <div class="text-xs mt-1">sm</div>
      </div>
      <div class="text-center">
        <sonic-icon library="heroicons" prefix="outline" name="academic-cap"></sonic-icon>
        <br />
        <div class="text-xs mt-1">default</div>
      </div>
      <div class="text-center">
        <sonic-icon library="heroicons" prefix="outline" name="academic-cap" size="lg"></sonic-icon>
        <br />
        <div class="text-xs mt-1">lg</div>
      </div>
      <div class="text-center">
        <sonic-icon library="heroicons" prefix="outline" name="academic-cap" size="xl"></sonic-icon>
        <br />
        <div class="text-xs mt-1">xl</div>
      </div>
      <div class="text-center">
        <sonic-icon library="heroicons" prefix="outline" name="academic-cap" size="2xl"></sonic-icon>
        <br />
        <div class="text-xs mt-1">2xl</div>
      </div>
      <div class="text-center">
        <sonic-icon library="heroicons" prefix="outline" name="academic-cap" size="3xl"></sonic-icon>
        <br />
        <div class="text-xs mt-1">3xl</div>
      </div>
    </div>
  </template>
</sonic-code>

## Accessibility

On connect, the host sets **`aria-hidden="true"`**. Treat icons as decorative unless the surrounding control already has an accessible name. Do not rely on **`sonic-icon`** alone for meaning—use visible text or **`aria-label`** on the parent button / link.

<sonic-code>
  <template>
    <sonic-button type="neutral" variant="outline" shape="circle" aria-label="Flight details">
      <sonic-icon library="iconoir" name="airplane"></sonic-icon>
    </sonic-button>
  </template>
</sonic-code>

## API reference

| Attribute | Values | Description |
|----------|---------|-------------|
| `name` | string | Icon id in the core bundle or in the remote library |
| `library` | `heroicons` · `iconoir` · `feathers` · `lucide` · `material` · `fontAwesome` · `custom` | CDN or custom template; omit for bundled core icons |
| `prefix` | string | Library-specific variant; defaults per library when empty |
| `size` | `2xs` · `xs` · `sm` · `lg` · `xl` · `2xl` · `3xl` (default `1em`, no attribute) | `em`-based SVG scale on the host |

Ancestor attributes (for **`library="custom"`** only): **`customIconLibraryPath`** (URL template with **`$prefix`** and **`$name`**) and **`customIconDefaultPrefix`**. May be set on **`sonic-scope`**, theme roots, or globally in the document.

No slots — the component inlines fetched or bundled SVG markup.