Since Shoelace 2.0 Code stable Pattern stable Figma ready

Icon

<sl-icon> | SlIcon

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"

import { SlIcon } from '@teamshares/shoelace/dist/react';

function FontAwesomeIcons() {
  const iconStyle = { fontSize: '20px' };

  return (
    <div style={iconStyle}>
      <p>Font Awesome icons</p>
      <ul>
        <li>Regular: <SlIcon library="fa" name="duck" /></li>
        <li>Solid: <SlIcon library="fa" name="fas-duck" /></li>
        <li>Light: <SlIcon library="fa" name="fal-duck" /></li>
        <li>Thin: <SlIcon library="fa" name="fat-duck" /></li>
        <li>Duotone: <SlIcon library="fa" name="fad-duck" /></li>
        <li>Brands: <SlIcon library="fa" name="fab-apple" /></li>
      </ul>
    </div>
  );
}

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. 

    <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);
  }

    import SlIcon from '@teamshares/shoelace/dist/react/icon';

const 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);
  }
`;

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

    <style>{css}</style>
  </>
);

    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);
  }

    import SlIcon from '@teamshares/shoelace/dist/react/icon';

const css = `
  .text-2xl {
    font-size: var(--sl-font-size-x-large);
  }
`;

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

  <style>{css}</style>
);

    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"

    import SlIcon from '@teamshares/shoelace/dist/react/icon';

const App = () => <SlIcon 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;"

    import SlIcon from '@teamshares/shoelace/dist/react/icon';

const App = () => <SlIcon src="https://shoelace.style/assets/images/shoe.svg" style={{ fontSize: '8rem' }}></SlIcon>;

    Importing

    If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

    Script Import Bundler React

    To import this component from the CDN using a script tag: 

    <script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.1.0/cdn/components/icon/icon.js"></script>

    To import this component from the CDN using a JavaScript import: 

    import 'https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.1.0/cdn/components/icon/icon.js';

    To import this component using a bundler: 

    import '@shoelace-style/shoelace/dist/components/icon/icon.js';

    To import this component as a React component: 

    import SlIcon from '@shoelace-style/shoelace/dist/react/icon';

    Properties

    Name Description Reflects Type Default
    name The name of the icon to draw. Available names depend on the icon library being used. string | undefined -
    src 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. string | undefined -
    label An alternate description to use for assistive devices. If omitted, the icon will be considered presentational and ignored by assistive devices. string ''
    library The name of a registered custom icon library. string 'default'
    updateComplete A read-only promise that resolves when the component has finished updating.

    Learn more about attributes and properties.

    Events

    Name React Event Description Event Detail
    sl-load onSlLoad Emitted when the icon has loaded. When using spriteSheet: true this will not emit. -
    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.

    Parts

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

    Learn more about customizing CSS parts.