Icon
Icon Sets
Font Awesome
Heroicons (Deprecated)
Examples
Colors
Sizing
Labels
Custom Icons
Component Props
Events
CSS Parts

Since Shoelace 2.0

Code stable

Pattern stable

Figma ready

Icon

sl-icon

Icons are symbols that can be used to represent various options within an application.

Icon Sets

Font Awesome

Our official Design System icon set is Font Awesome. Use Font Awesome icons in Shoelace by setting the sl-icon’s library attribute to fa and passing the icon’s name to the name attribute.

This will display Regular style icons by default:

sl-icon library="fa" name="user"

To display icons in one of the other Font Awesome styles (solid, light, thin, duotone, brands), add one of the following prefixes to the icon name:

To display a solid icon -> add the fas- prefix
To display a light icon -> add the fal- prefix
To display a thin icon -> add the fat- prefix
To display a duotone icon -> add the fad- prefix
To display a brand icon (for social media icons, etc.) -> add the fab- prefix

Note that some icons only exist in one style.

Font Awesome icons

Regular:
Solid:
Light:
Thin:
Duotone:
Brands:

<div style="font-size: 20px;">
  <p>Font Awesome icons</p>
  <ul>
    <li>Regular: <sl-icon library="fa" name="duck"></sl-icon></li>
    <li>Solid: <sl-icon library="fa" name="fas-duck"></sl-icon></li>
    <li>Light: <sl-icon library="fa" name="fal-duck"></sl-icon></li>
    <li>Thin: <sl-icon library="fa" name="fat-duck"></sl-icon></li>
    <li>Duotone: <sl-icon library="fa" name="fad-duck"></sl-icon></li>
    <li>Brands: <sl-icon library="fa" name="fab-apple"></sl-icon></li>
  </ul>
</div>

div style="font-size: 20px;"
  p Font Awesome icons
  ul
    li Regular: sl-icon library="fa" name="duck"
    li Solid: sl-icon library="fa" name="fas-duck"
    li Light: sl-icon library="fa" name="fal-duck"
    li Thin: sl-icon library="fa" name="fat-duck"
    li Duotone: sl-icon library="fa" name="fad-duck"
    li Brands: sl-icon library="fa" name="fab-apple"

Not sure what the icon you want is called?

Search the Font Awesome site using the input below:

The Design System is currently able to display icons up to version 6.5.1

Heroicons (Deprecated)

Not setting the sl-icon’s library attribute to fa will display an icon from our previous (now deprecated) icon set, Heroicons. Although Heroicons are still available to use, please use only Font Awesome icons in new designs!

This is a Heroicon icon:

This is a Font Awesome icon:

<li>This is a Heroicon icon: <sl-icon name="hand-raised"></sl-icon></li>
<li>This is a Font Awesome icon: <sl-icon library="fa" name="thumbs-up"></sl-icon></li>

li This is a Heroicon icon: sl-icon name="hand-raised"
li This is a Font Awesome icon: sl-icon library="fa" name="thumbs-up"

Examples

Colors

Icons inherit their color from the current text color. Thus, you can set the color property on the <sl-icon> element or an ancestor to change the color, ideally using Tailwind’s utility classes for text colors (e.g. text-blue-700). Only use colors from our Colors page.

Make sure icon meets AA contrast requirements.

Icon colors can vary depending on context, but make sure that there is enough contrast between the icon color and the background color to meet the WCAG AA minimum contrast requirements for icons (3:1).

<div class="text-gray-600">
  <sl-icon library="fa" name="exclamation-triangle"></sl-icon>
  <sl-icon library="fa" name="box-archive"></sl-icon>
  <sl-icon library="fa" name="battery-three-quarters"></sl-icon>
  <sl-icon library="fa" name="bell"></sl-icon>
</div>
<div class="text-blue-600">
  <sl-icon library="fa" name="clock"></sl-icon>
  <sl-icon library="fa" name="cloud"></sl-icon>
  <sl-icon library="fa" name="arrow-down-to-bracket"></sl-icon>
  <sl-icon library="fa" name="folder"></sl-icon>
</div>
<div class="text-teal-600">
  <sl-icon library="fa" name="flag"></sl-icon>
  <sl-icon library="fa" name="heart"></sl-icon>
  <sl-icon library="fa" name="image"></sl-icon>
  <sl-icon library="fa" name="bolt"></sl-icon>
</div>
<div class="text-red-600">
  <sl-icon library="fa" name="microphone"></sl-icon>
  <sl-icon library="fa" name="magnifying-glass"></sl-icon>
  <sl-icon library="fa" name="star"></sl-icon>
  <sl-icon library="fa" name="trash"></sl-icon>
</div>

<style>
  .text-gray-600 {
    color: var(--sl-color-gray-600);
  }
  .text-blue-600 {
    color: var(--sl-color-blue-600);
  }
  .text-teal-600 {
    color: var(--sl-color-teal-600);
  }
  .text-red-600 {
    color: var(--sl-color-red-600);
  }
</style>

div class="text-gray-600"
  sl-icon library="fa" name="exclamation-triangle"
  sl-icon library="fa" name="box-archive"
  sl-icon library="fa" name="battery-three-quarters"
  sl-icon library="fa" name="bell"
div class="text-blue-960000"
  sl-icon library="fa" name="clock"
  sl-icon library="fa" name="cloud"
  sl-icon library="fa" name="arrow-down-to-bracket"
  sl-icon library="fa" name="folder"
div class="text-teal-600"
  sl-icon library="fa" name="flag"
  sl-icon library="fa" name="heart"
  sl-icon library="fa" name="image"
  sl-icon library="fa" name="bolt"
div class="text-red-600"
  sl-icon library="fa" name="microphone"
  sl-icon library="fa" name="magnifying-glass"
  sl-icon library="fa" name="star"
  sl-icon library="fa" name="trash"

css:
  .text-gray-600 {
    color: var(--sl-color-gray-600);
  }
  .text-blue-600 {
    color: var(--sl-color-blue-600);
  }
  .text-teal-600 {
    color: var(--sl-color-teal-600);
  }
  .text-red-600 {
    color: var(--sl-color-red-600);
  }

Sizing

Icons are sized relative to the current font size. To change their size, set the font-size property on the icon itself or on a parent element, ideally using Tailwind’s utility classes for font size (e.g. text-2xl).

<div class="text-2xl">
  <sl-icon library="fa" name="exclamation-triangle"></sl-icon>
  <sl-icon library="fa" name="box-archive"></sl-icon>
  <sl-icon library="fa" name="battery-three-quarters"></sl-icon>
  <sl-icon library="fa" name="bell"></sl-icon>
  <sl-icon library="fa" name="clock"></sl-icon>
  <sl-icon library="fa" name="cloud"></sl-icon>
  <sl-icon library="fa" name="arrow-down-to-bracket"></sl-icon>
  <sl-icon library="fa" name="folder"></sl-icon>
  <sl-icon library="fa" name="flag"></sl-icon>
  <sl-icon library="fa" name="heart"></sl-icon>
  <sl-icon library="fa" name="image"></sl-icon>
  <sl-icon library="fa" name="bolt"></sl-icon>
  <sl-icon library="fa" name="microphone"></sl-icon>
  <sl-icon library="fa" name="magnifying-glass"></sl-icon>
  <sl-icon library="fa" name="star"></sl-icon>
  <sl-icon library="fa" name="trash"></sl-icon>
</div>

<style>
  .text-2xl {
    font-size: var(--sl-font-size-x-large);
  }
</style>

div class="text-2xl"
  sl-icon library="fa" library="fa" name="exclamation-triangle"
  sl-icon library="fa" name="box-archive"
  sl-icon library="fa" name="battery-three-quarters"
  sl-icon library="fa" name="bell"
  sl-icon library="fa" name="clock"
  sl-icon library="fa" name="cloud"
  sl-icon library="fa" name="arrow-down-to-bracket"
  sl-icon library="fa" name="folder"
  sl-icon library="fa" name="flag"
  sl-icon library="fa" name="heart"
  sl-icon library="fa" name="image"
  sl-icon library="fa" name="bolt"
  sl-icon library="fa" name="microphone"
  sl-icon library="fa" name="magnifying-glass"
  sl-icon library="fa" name="star"
  sl-icon library="fa" name="trash"
css:
  .text-2xl {
    font-size: var(--sl-font-size-x-large);
  }

Labels

For non-decorative icons, use the label attribute to announce it to assistive devices.

<sl-icon library="fa" name="heart" label="Add to favorites"></sl-icon>

sl-icon library="fa" name="heart" label="Add to favorites"

Custom Icons

Custom icons can be loaded individually with the src attribute. Only SVGs on a local or CORS-enabled endpoint are supported. If you’re using more than one custom icon, it might make sense to register a custom icon library.

<sl-icon src="https://shoelace.style/assets/images/shoe.svg" style="font-size: 8rem;"></sl-icon>

sl-icon src="https://shoelace.style/assets/images/shoe.svg" style="font-size: 8rem;"

Component Props

Property	Default	Details
`name`	—	`string \| undefined` The name of the icon to draw. Available names depend on the icon library being used.
`src`	—	`string \| undefined` An external URL of an SVG file. Be sure you trust the content you are including, as it will be executed as code and can result in XSS attacks.
`label`	`''`	`string` An alternate description to use for assistive devices. If omitted, the icon will be considered presentational and ignored by assistive devices.
`library`	`'default'`	`string` The name of a registered custom icon library.
`updateComplete`		A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Events

Name	Name	Name	React Event	Details
`sl-load`	`sl-load`	`sl-load`	`onSlLoad`	Emitted when the icon has loaded. When using `spriteSheet: true` this will not emit.
`sl-error`	`sl-error`	`sl-error`	`onSlError`	Emitted when the icon fails to load due to an error. When using `spriteSheet: true` this will not emit.

Learn more about events.

CSS Parts

Name	Description
`svg`	The internal SVG element.
`use`	The element generated when using `spriteSheet: true`

Learn more about customizing CSS parts.