Icon

<wa-icon>

Since 2.0

stable

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

Web Awesome comes bundled with over 2,000 free icons courtesy of Font Awesome. These icons are part of the default icon library. Font Awesome Pro users can unlock additional icon families. Or, if you prefer, you can register your own custom icon library.

<wa-icon name="face-awesome" variant="light" label="Awesome" style="font-size: 2em;"></wa-icon>

Not sure which icon to use? Find the perfect icon over at Font Awesome!

Examples Jump to heading

Families & Variants Jump to heading

The default icon library is Font Awesome Free, which comes with two icon families: classic and brands. Use the family attribute to set the icon family.

Many Font Awesome Pro icon families have variants such as thin, light, regular, and solid. Font Awesome Pro users can provide their kit code to unlock additional premium icon families, including sharp, duotone, sharp-duotone, and additional Pro+ icon packs.

For supportive icon families, use the variant attribute to set the variant.

Classic
      
Duotone
      
Sharp
      
Sharp Duotone
      
Brands

<div class="wa-stack wa-gap-xl">
  <div class="wa-flank" style="--flank-size: 12ch;">
    <span>Classic</span>
    <div class="wa-cluster" style="font-size: 1.5em;">
      <wa-icon name="eyedropper"></wa-icon>
      <wa-icon variant="regular" name="grip-vertical"></wa-icon>
      <wa-icon variant="light" name="play"></wa-icon>
      <wa-icon variant="thin" name="star"></wa-icon>
    </div>
  </div>
  <div class="wa-flank" style="--flank-size: 12ch;">
    <span>Duotone</span>
    <div class="wa-cluster" style="font-size: 1.5em;">
      <wa-icon family="duotone" name="eyedropper"></wa-icon>
      <wa-icon family="duotone" variant="regular" name="grip-vertical"></wa-icon>
      <wa-icon family="duotone" variant="light" name="play"></wa-icon>
      <wa-icon family="duotone" variant="thin" name="star"></wa-icon>
    </div>
  </div>
  <div class="wa-flank" style="--flank-size: 12ch;">
    <span>Sharp</span>
    <div class="wa-cluster" style="font-size: 1.5em;">
      <wa-icon family="sharp" name="eyedropper"></wa-icon>
      <wa-icon family="sharp" variant="regular" name="grip-vertical"></wa-icon>
      <wa-icon family="sharp" variant="light" name="play"></wa-icon>
      <wa-icon family="sharp" variant="thin" name="star"></wa-icon>
    </div>
  </div>
  <div class="wa-flank" style="--flank-size: 12ch;">
    <span>Sharp Duotone</span>
    <div class="wa-cluster" style="font-size: 1.5em;">
      <wa-icon family="sharp-duotone" name="eyedropper"></wa-icon>
      <wa-icon family="sharp-duotone" variant="regular" name="grip-vertical"></wa-icon>
      <wa-icon family="sharp-duotone" variant="light" name="play"></wa-icon>
      <wa-icon family="sharp-duotone" variant="thin" name="star"></wa-icon>
    </div>
  </div>
  <div class="wa-flank" style="--flank-size: 12ch;">
    <span>Brands</span>
    <div class="wa-cluster" style="font-size: 1.5em;">
      <wa-icon family="brands" name="font-awesome"></wa-icon>
      <wa-icon family="brands" name="web-awesome"></wa-icon>
      <wa-icon family="brands" name="github"></wa-icon>
      <wa-icon family="brands" name="discord"></wa-icon>
    </div>
  </div>
</div>

Labels Jump to heading

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

<wa-icon name="star" label="Favorite" style="font-size: 1.5em;"></wa-icon>

Sizing Jump to heading

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 as shown below.

<div class="wa-cluster" style="font-size: 44px;">
  <wa-icon name="bell"></wa-icon>
  <wa-icon name="heart"></wa-icon>
  <wa-icon name="image"></wa-icon>
  <wa-icon name="microphone"></wa-icon>
  <wa-icon name="search"></wa-icon>
  <wa-icon name="star"></wa-icon>
</div>

Auto Width Jump to heading

By default, icons have a 1em height and a fixed 1.25em width. Use the auto-width attribute to allow the icon to use its natural variable width.

                Without auto-width

With auto-width

Without auto-width<br />
<div style="font-size: 1.5em; color: #193154;">
  <wa-icon family="solid" name="exclamation" style="background: lightsalmon;"></wa-icon>
  <wa-icon family="solid" name="circle-check" style="background: lightsalmon;"></wa-icon>
  <wa-icon family="solid" name="input-numeric" style="background: lightsalmon;"></wa-icon>
  <wa-icon family="solid" name="ruler-vertical" style="background: lightsalmon;"></wa-icon>
  <wa-icon family="solid" name="ruler-horizontal" style="background: lightsalmon;"></wa-icon>
  <wa-icon family="solid" name="airplay" style="background: lightsalmon;"></wa-icon>
</div>

<br />

With auto-width<br />
<div style="font-size: 1.5em; color: #193154;">
  <wa-icon auto-width family="solid" name="exclamation" style="background: lightsalmon;"></wa-icon>
  <wa-icon auto-width family="solid" name="circle-check" style="background: lightsalmon;"></wa-icon>
  <wa-icon auto-width family="solid" name="input-numeric" style="background: lightsalmon;"></wa-icon>
  <wa-icon auto-width family="solid" name="ruler-vertical" style="background: lightsalmon;"></wa-icon>
  <wa-icon auto-width family="solid" name="ruler-horizontal" style="background: lightsalmon;"></wa-icon>
  <wa-icon auto-width family="solid" name="airplay" style="background: lightsalmon;"></wa-icon>
</div>

Colors Jump to heading

Icons inherit their color from the current text color. Thus, you can set the color property on the <wa-icon> element or an ancestor to change the color.

<div class="wa-cluster" style="font-size: 1.5em;">
  <wa-icon name="strawberry" style="color: salmon;"></wa-icon>
  <wa-icon name="crab" style="color: coral;"></wa-icon>
  <wa-icon name="sun" style="color: gold;"></wa-icon>
  <wa-icon name="leaf" style="color: mediumseagreen;"></wa-icon>
  <wa-icon name="cloud-showers-heavy" style="color: steelblue;"></wa-icon>
  <wa-icon name="cat-space" style="color: mediumpurple;"></wa-icon>
</div>

Duotone Jump to heading

Font Awesome's Duotone icons change with the color property as well, but you can customize the primary and secondary colors independently using the --primary-color and --secondary-color custom properties. To change the opacity of either, use --primary-opacity and --secondary-opacity.

Note that these custom properties will not inherit and must be applied directly to the icon.

<div class="wa-stack">
  <div class="wa-cluster" style="font-size: 1.5em;">
    <wa-icon
      family="duotone"
      name="crow"
      style="--primary-color: dodgerblue; --secondary-color: gold; --secondary-opacity: 1.0;"
    ></wa-icon>
    <wa-icon
      family="duotone"
      name="campfire"
      style="--primary-color: sienna; --secondary-color: red; --secondary-opacity: 1.0;"
    ></wa-icon>
    <wa-icon
      family="duotone"
      name="birthday-cake"
      style="--primary-color: pink; --secondary-color: palevioletred; --secondary-opacity: 1.0;"
    ></wa-icon>
    <wa-icon
      family="duotone"
      name="ear"
      style="--primary-color: sandybrown; --secondary-color: bisque; --secondary-opacity: 1.0;"
    ></wa-icon>
    <wa-icon
      family="duotone"
      name="corn"
      style="--primary-color: mediumseagreen; --secondary-color: gold; --secondary-opacity: 1.0;"
    ></wa-icon>
    <wa-icon
      family="duotone"
      name="cookie-bite"
      style="--primary-color: saddlebrown; --secondary-color: burlywood; --secondary-opacity: 1.0;"
    ></wa-icon>
  </div>

  <div class="wa-cluster" style="font-size: 1.5em;">
    <wa-icon
      family="duotone"
      variant="regular"
      name="crow"
      style="--primary-color: dodgerblue; --secondary-color: gold; --secondary-opacity: 1.0;"
    ></wa-icon>
    <wa-icon
      family="duotone"
      variant="regular"
      name="campfire"
      style="--primary-color: sienna; --secondary-color: red; --secondary-opacity: 1.0;"
    ></wa-icon>
    <wa-icon
      family="duotone"
      variant="regular"
      name="birthday-cake"
      style="--primary-color: pink; --secondary-color: palevioletred; --secondary-opacity: 1.0;"
    ></wa-icon>
    <wa-icon
      family="duotone"
      variant="regular"
      name="ear"
      style="--primary-color: sandybrown; --secondary-color: bisque; --secondary-opacity: 1.0;"
    ></wa-icon>
    <wa-icon
      family="duotone"
      variant="regular"
      name="corn"
      style="--primary-color: mediumseagreen; --secondary-color: gold; --secondary-opacity: 1.0;"
    ></wa-icon>
    <wa-icon
      family="duotone"
      variant="regular"
      name="cookie-bite"
      style="--primary-color: saddlebrown; --secondary-color: burlywood; --secondary-opacity: 1.0;"
    ></wa-icon>
  </div>

  <div class="wa-cluster" style="font-size: 1.5em;">
    <wa-icon
      family="duotone"
      variant="light"
      name="crow"
      style="--primary-color: dodgerblue; --secondary-color: gold; --secondary-opacity: 1.0;"
    ></wa-icon>
    <wa-icon
      family="duotone"
      variant="light"
      name="campfire"
      style="--primary-color: sienna; --secondary-color: red; --secondary-opacity: 1.0;"
    ></wa-icon>
    <wa-icon
      family="duotone"
      variant="light"
      name="birthday-cake"
      style="--primary-color: pink; --secondary-color: palevioletred; --secondary-opacity: 1.0;"
    ></wa-icon>
    <wa-icon
      family="duotone"
      variant="light"
      name="ear"
      style="--primary-color: sandybrown; --secondary-color: bisque; --secondary-opacity: 1.0;"
    ></wa-icon>
    <wa-icon
      family="duotone"
      variant="light"
      name="corn"
      style="--primary-color: mediumseagreen; --secondary-color: gold; --secondary-opacity: 1.0;"
    ></wa-icon>
    <wa-icon
      family="duotone"
      variant="light"
      name="cookie-bite"
      style="--primary-color: saddlebrown; --secondary-color: burlywood; --secondary-opacity: 1.0;"
    ></wa-icon>
  </div>

  <div class="wa-cluster" style="font-size: 1.5em;">
    <wa-icon
      family="duotone"
      variant="thin"
      name="crow"
      style="--primary-color: dodgerblue; --secondary-color: gold; --secondary-opacity: 1.0;"
    ></wa-icon>
    <wa-icon
      family="duotone"
      variant="thin"
      name="campfire"
      style="--primary-color: sienna; --secondary-color: red; --secondary-opacity: 1.0;"
    ></wa-icon>
    <wa-icon
      family="duotone"
      variant="thin"
      name="birthday-cake"
      style="--primary-color: pink; --secondary-color: palevioletred; --secondary-opacity: 1.0;"
    ></wa-icon>
    <wa-icon
      family="duotone"
      variant="thin"
      name="ear"
      style="--primary-color: sandybrown; --secondary-color: bisque; --secondary-opacity: 1.0;"
    ></wa-icon>
    <wa-icon
      family="duotone"
      variant="thin"
      name="corn"
      style="--primary-color: mediumseagreen; --secondary-color: gold; --secondary-opacity: 1.0;"
    ></wa-icon>
    <wa-icon
      family="duotone"
      variant="thin"
      name="cookie-bite"
      style="--primary-color: saddlebrown; --secondary-color: burlywood; --secondary-opacity: 1.0;"
    ></wa-icon>
  </div>
</div>

Duotone icons can be unlocked by providing a valid Font Awesome kit code.

Swap Duotone Opacity Jump to heading

For duotone icons, you can swap the primary and secondary opacity values using the swap-opacity attribute. This is useful when you want to emphasize the secondary layer of the icon.

                Normal duotone

Swapped duotone

Normal duotone<br />
<div class="wa-cluster" style="font-size: 1.5em;">
  <wa-icon family="duotone" name="home"></wa-icon>
  <wa-icon family="duotone" name="user"></wa-icon>
  <wa-icon family="duotone" name="envelope"></wa-icon>
  <wa-icon family="duotone" name="calendar"></wa-icon>
</div>

<br />

Swapped duotone<br />
<div class="wa-cluster" style="font-size: 1.5em;">
  <wa-icon family="duotone" name="home" swap-opacity></wa-icon>
  <wa-icon family="duotone" name="user" swap-opacity></wa-icon>
  <wa-icon family="duotone" name="envelope" swap-opacity></wa-icon>
  <wa-icon family="duotone" name="calendar" swap-opacity></wa-icon>
</div>

Font Awesome Pro+ Jump to heading

If you're a Font Awesome Pro+ customer, you have access to even more premium icons! Just set the appropriate family, variant, and name on the icon.

Notdog

Chisel

Etch

Jelly

Slab

Thumbprint

Whiteboard

<div class="wa-stack wa-gap-xl">
  <div class="wa-flank" style="--flank-size: 10ch;">
    <a href="https://fontawesome.com/icons/packs/notdog" target="_blank">Notdog</a>
    <div class="wa-cluster" style="font-size: 1.5em;">
      <wa-icon family="notdog" variant="solid" name="house"></wa-icon>
      <wa-icon
        family="notdog"
        variant="duo-solid"
        name="house"
        style="--secondary-color: skyblue; --secondary-opacity: 0.8;"
      ></wa-icon>
    </div>
  </div>

  <div class="wa-flank" style="--flank-size: 10ch;">
    <a href="https://fontawesome.com/icons/packs/chisel" target="_blank">Chisel</a>
    <div class="wa-cluster" style="font-size: 1.5em;">
      <wa-icon family="chisel" variant="regular" name="house"></wa-icon>
    </div>
  </div>

  <div class="wa-flank" style="--flank-size: 10ch;">
    <a href="https://fontawesome.com/icons/packs/etch" target="_blank">Etch</a>
    <div class="wa-cluster" style="font-size: 1.5em;">
      <wa-icon family="etch" variant="solid" name="house"></wa-icon>
    </div>
  </div>

  <div class="wa-flank" style="--flank-size: 10ch;">
    <a href="https://fontawesome.com/icons/packs/jelly" target="_blank">Jelly</a>
    <div class="wa-cluster" style="font-size: 1.5em;">
      <wa-icon family="jelly" variant="regular" name="house"></wa-icon>
      <wa-icon
        family="jelly"
        variant="duo-regular"
        name="house"
        style="--secondary-color: skyblue; --secondary-opacity: 0.8;"
      ></wa-icon>
      <wa-icon family="jelly" variant="fill-regular" name="house"></wa-icon>
    </div>
  </div>

  <div class="wa-flank" style="--flank-size: 10ch;">
    <a href="https://fontawesome.com/icons/packs/slab" target="_blank">Slab</a>
    <div class="wa-cluster" style="font-size: 1.5em;">
      <wa-icon family="slab" variant="regular" name="house"></wa-icon>
      <wa-icon family="slab" variant="press-regular" name="house"></wa-icon>
    </div>
  </div>

  <div class="wa-flank" style="--flank-size: 10ch;">
    <a href="https://fontawesome.com/icons/packs/thumbprint" target="_blank">Thumbprint</a>
    <div class="wa-cluster" style="font-size: 1.5em;">
      <wa-icon
        family="thumbprint"
        variant="light"
        name="house"
        style="--secondary-color: skyblue; --secondary-opacity: 0.8;"
      ></wa-icon>
    </div>
  </div>

  <div class="wa-flank" style="--flank-size: 10ch;">
    <a href="https://fontawesome.com/icons/packs/whiteboard" target="_blank">Whiteboard</a>
    <div class="wa-cluster" style="font-size: 32px;">
      <wa-icon family="whiteboard" variant="semibold" name="house"></wa-icon>
    </div>
  </div>
</div>

Pro+ icons can be unlocked by providing a valid Font Awesome kit code.

Custom Icons Jump to heading

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.

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

Icon Libraries Jump to heading

You can register additional icons to use with the <wa-icon> component through icon libraries. Icon files can exist locally or on a CORS-enabled endpoint (e.g. a CDN). There is no limit to how many icon libraries you can register and there is no cost associated with registering them, as individual icons are only requested when they're used.

Web Awesome ships with two built-in icon libraries, default and system. The default icon library is provided courtesy of Font Awesome. The system icon library contains only a small subset of icons that are used internally by Web Awesome components.

To register an additional icon library, use the registerIconLibrary() function that's exported from dist/webawesome.js. At a minimum, you must provide a name and a resolver function. The resolver function translates an icon name to a URL where the corresponding SVG file exists. Refer to the examples below to better understand how it works.

If necessary, a mutator function can be used to mutate the SVG element before rendering. This is necessary for some libraries due to the many possible ways SVGs are crafted. For example, icons should ideally inherit the current text color via currentColor, so you may need to apply fill="currentColor or stroke="currentColor" to the SVG element using this function.

Here's an example that registers an icon library located in the /assets/icons directory.

<script type="module">
  import { registerIconLibrary } from '/dist/webawesome.js';

  registerIconLibrary('my-icons', {
    resolver: (name, family, variant) => `/assets/icons/${name}.svg`,
    mutator: svg => svg.setAttribute('fill', 'currentColor'),
  });
</script>

To display an icon, set the library and name attributes of an <wa-icon> element.

<!-- This will show the icon located at /assets/icons/smile.svg -->
<wa-icon library="my-icons" name="smile"></wa-icon>

If an icon is used before registration occurs, it will be empty initially but shown when registered.

The following examples demonstrate how to register a number of popular, open source icon libraries via CDN. Feel free to adapt the code as you see fit to use your own origin or naming conventions.

Bootstrap Icons Jump to heading

This will register the Bootstrap Icons library using the jsDelivr CDN. This library has two families: regular and filled.

Icons in this library are licensed under the MIT License.

<script type="module">
  import { registerIconLibrary } from '/dist/webawesome.js';

  registerIconLibrary('bootstrap', {
    resolver: (name, family) => {
      const suffix = family === 'filled' ? '-fill' : '';
      return `https://cdn.jsdelivr.net/npm/[email protected]/icons/${name}${suffix}.svg`;
    },
  });
</script>

<div style="font-size: 24px;">
  <wa-icon library="bootstrap" name="backpack"></wa-icon>
  <wa-icon library="bootstrap" name="cup-hot"></wa-icon>
  <wa-icon library="bootstrap" name="envelope-heart"></wa-icon>
  <wa-icon library="bootstrap" name="inboxes"></wa-icon>
  <wa-icon library="bootstrap" name="lamp"></wa-icon>
  <wa-icon library="bootstrap" name="piggy-bank"></wa-icon>
  <br />
  <wa-icon library="bootstrap" family="filled" name="backpack"></wa-icon>
  <wa-icon library="bootstrap" family="filled" name="cup-hot"></wa-icon>
  <wa-icon library="bootstrap" family="filled" name="envelope-heart"></wa-icon>
  <wa-icon library="bootstrap" family="filled" name="inboxes"></wa-icon>
  <wa-icon library="bootstrap" family="filled" name="lamp"></wa-icon>
  <wa-icon library="bootstrap" family="filled" name="piggy-bank"></wa-icon>
</div>

Boxicons Jump to heading

This will register the Boxicons library using the jsDelivr CDN. This library has three variations: regular (bx-*), solid (bxs-*), and logos (bxl-*). A mutator function is required to set the SVG's fill to currentColor.

Icons in this library are licensed under the Creative Commons 4.0 License.

<script type="module">
  import { registerIconLibrary } from '/dist/webawesome.js';

  registerIconLibrary('boxicons', {
    resolver: name => {
      let folder = 'regular';
      if (name.substring(0, 4) === 'bxs-') folder = 'solid';
      if (name.substring(0, 4) === 'bxl-') folder = 'logos';
      return `https://cdn.jsdelivr.net/npm/[email protected]/svg/${folder}/${name}.svg`;
    },
    mutator: svg => svg.setAttribute('fill', 'currentColor'),
  });
</script>

<div style="font-size: 24px;">
  <wa-icon library="boxicons" name="bx-bot"></wa-icon>
  <wa-icon library="boxicons" name="bx-cookie"></wa-icon>
  <wa-icon library="boxicons" name="bx-joystick"></wa-icon>
  <wa-icon library="boxicons" name="bx-save"></wa-icon>
  <wa-icon library="boxicons" name="bx-server"></wa-icon>
  <wa-icon library="boxicons" name="bx-wine"></wa-icon>
  <br />
  <wa-icon library="boxicons" name="bxs-bot"></wa-icon>
  <wa-icon library="boxicons" name="bxs-cookie"></wa-icon>
  <wa-icon library="boxicons" name="bxs-joystick"></wa-icon>
  <wa-icon library="boxicons" name="bxs-save"></wa-icon>
  <wa-icon library="boxicons" name="bxs-server"></wa-icon>
  <wa-icon library="boxicons" name="bxs-wine"></wa-icon>
  <br />
  <wa-icon library="boxicons" name="bxl-apple"></wa-icon>
  <wa-icon library="boxicons" name="bxl-chrome"></wa-icon>
  <wa-icon library="boxicons" name="bxl-edge"></wa-icon>
  <wa-icon library="boxicons" name="bxl-firefox"></wa-icon>
  <wa-icon library="boxicons" name="bxl-opera"></wa-icon>
  <wa-icon library="boxicons" name="bxl-microsoft"></wa-icon>
</div>

Lucide Jump to heading

This will register the Lucide icon library using the jsDelivr CDN. This project is a community-maintained fork of the popular Feather icon library.

Icons in this library are licensed under the MIT License.

<script type="module">
  import { registerIconLibrary } from '/dist/webawesome.js';

  registerIconLibrary('lucide', {
    resolver: name => `https://cdn.jsdelivr.net/npm/[email protected]/icons/${name}.svg`,
    mutator: svg =>
      svg.querySelectorAll('path').forEach(path => {
        path.setAttribute('fill', 'none');
        path.setAttribute('stroke', 'currentColor');
      }),
  });
</script>

<div style="font-size: 24px;">
  <wa-icon library="lucide" name="feather"></wa-icon>
  <wa-icon library="lucide" name="pie-chart"></wa-icon>
  <wa-icon library="lucide" name="settings"></wa-icon>
  <wa-icon library="lucide" name="map-pin"></wa-icon>
  <wa-icon library="lucide" name="printer"></wa-icon>
  <wa-icon library="lucide" name="shopping-cart"></wa-icon>
</div>

Heroicons Jump to heading

This will register the Heroicons library using the jsDelivr CDN.

Icons in this library are licensed under the MIT License.

<script type="module">
  import { registerIconLibrary } from '/dist/webawesome.js';

  registerIconLibrary('heroicons', {
    resolver: name => `https://cdn.jsdelivr.net/npm/[email protected]/24/outline/${name}.svg`,
    mutator: svg =>
      svg.querySelectorAll('path').forEach(path => {
        path.setAttribute('fill', 'none');
        path.setAttribute('stroke', 'currentColor');
      }),
  });
</script>

<div style="font-size: 24px;">
  <wa-icon library="heroicons" name="chat-bubble-left"></wa-icon>
  <wa-icon library="heroicons" name="cloud"></wa-icon>
  <wa-icon library="heroicons" name="cog"></wa-icon>
  <wa-icon library="heroicons" name="document-text"></wa-icon>
  <wa-icon library="heroicons" name="gift"></wa-icon>
  <wa-icon library="heroicons" name="speaker-wave"></wa-icon>
</div>

Iconoir Jump to heading

This will register the Iconoir library using the jsDelivr CDN.

Icons in this library are licensed under the MIT License.

<script type="module">
  import { registerIconLibrary } from '/dist/webawesome.js';

  registerIconLibrary('iconoir', {
    resolver: (name, family) => {
      return `https://cdn.jsdelivr.net/npm/[email protected]/icons/regular/${name}.svg`;
    },
    mutator: svg =>
      svg.querySelectorAll('path').forEach(path => {
        path.setAttribute('fill', 'none');
        path.setAttribute('stroke', 'currentColor');
      }),
  });
</script>

<div style="font-size: 24px;">
  <wa-icon library="iconoir" name="check-circle"></wa-icon>
  <wa-icon library="iconoir" name="drawer"></wa-icon>
  <wa-icon library="iconoir" name="keyframes"></wa-icon>
  <wa-icon library="iconoir" name="headset-help"></wa-icon>
  <wa-icon library="iconoir" name="color-picker"></wa-icon>
  <wa-icon library="iconoir" name="wifi"></wa-icon>
</div>

Ionicons Jump to heading

This will register the Ionicons library using the jsDelivr CDN. This library has three variations: outline (default), filled (*-filled), and sharp (*-sharp). A mutator function is required to polyfill a handful of styles we're not including.

Icons in this library are licensed under the MIT License.

<script type="module">
  import { registerIconLibrary } from '/dist/webawesome.js';

  registerIconLibrary('ionicons', {
    resolver: name => `https://cdn.jsdelivr.net/npm/[email protected]/dist/ionicons/svg/${name}.svg`,
    mutator: svg => {
      svg.setAttribute('fill', 'currentColor');
      svg.setAttribute('stroke', 'currentColor');
      [...svg.querySelectorAll('.ionicon-fill-none')].map(el => el.setAttribute('fill', 'none'));
      [...svg.querySelectorAll('.ionicon-stroke-width')].map(el => el.setAttribute('stroke-width', '32px'));
    },
  });
</script>

<div style="font-size: 24px;">
  <wa-icon library="ionicons" name="alarm"></wa-icon>
  <wa-icon library="ionicons" name="american-football"></wa-icon>
  <wa-icon library="ionicons" name="bug"></wa-icon>
  <wa-icon library="ionicons" name="chatbubble"></wa-icon>
  <wa-icon library="ionicons" name="settings"></wa-icon>
  <wa-icon library="ionicons" name="warning"></wa-icon>
  <br />
  <wa-icon library="ionicons" name="alarm-outline"></wa-icon>
  <wa-icon library="ionicons" name="american-football-outline"></wa-icon>
  <wa-icon library="ionicons" name="bug-outline"></wa-icon>
  <wa-icon library="ionicons" name="chatbubble-outline"></wa-icon>
  <wa-icon library="ionicons" name="settings-outline"></wa-icon>
  <wa-icon library="ionicons" name="warning-outline"></wa-icon>
  <br />
  <wa-icon library="ionicons" name="alarm-sharp"></wa-icon>
  <wa-icon library="ionicons" name="american-football-sharp"></wa-icon>
  <wa-icon library="ionicons" name="bug-sharp"></wa-icon>
  <wa-icon library="ionicons" name="chatbubble-sharp"></wa-icon>
  <wa-icon library="ionicons" name="settings-sharp"></wa-icon>
  <wa-icon library="ionicons" name="warning-sharp"></wa-icon>
</div>

Jam Icons Jump to heading

This will register the Jam Icons library using the jsDelivr CDN. This library has two variations: regular (default) and filled (*-f). A mutator function is required to set the SVG's fill to currentColor.

Icons in this library are licensed under the MIT License.

<script type="module">
  import { registerIconLibrary } from '/dist/webawesome.js';

  registerIconLibrary('jam', {
    resolver: name => `https://cdn.jsdelivr.net/npm/[email protected]/svg/${name}.svg`,
    mutator: svg => svg.setAttribute('fill', 'currentColor'),
  });
</script>

<div style="font-size: 24px;">
  <wa-icon library="jam" name="calendar"></wa-icon>
  <wa-icon library="jam" name="camera"></wa-icon>
  <wa-icon library="jam" name="filter"></wa-icon>
  <wa-icon library="jam" name="leaf"></wa-icon>
  <wa-icon library="jam" name="picture"></wa-icon>
  <wa-icon library="jam" name="set-square"></wa-icon>
  <br />
  <wa-icon library="jam" name="calendar-f"></wa-icon>
  <wa-icon library="jam" name="camera-f"></wa-icon>
  <wa-icon library="jam" name="filter-f"></wa-icon>
  <wa-icon library="jam" name="leaf-f"></wa-icon>
  <wa-icon library="jam" name="picture-f"></wa-icon>
  <wa-icon library="jam" name="set-square-f"></wa-icon>
</div>

Material Icons Jump to heading

This will register the Material Icons library using the jsDelivr CDN. This library has three variations: outline (default), round (*_round), and sharp (*_sharp). A mutator function is required to set the SVG's fill to currentColor.

Icons in this library are licensed under the Apache 2.0 License.

<script type="module">
  import { registerIconLibrary } from '/dist/webawesome.js';

  registerIconLibrary('material', {
    resolver: name => {
      const match = name.match(/^(.*?)(_(round|sharp))?$/);
      return `https://cdn.jsdelivr.net/npm/@material-icons/[email protected]/svg/${match[1]}/${match[3] || 'outline'}.svg`;
    },
    mutator: svg => svg.setAttribute('fill', 'currentColor'),
  });
</script>

<div style="font-size: 24px;">
  <wa-icon library="material" name="notifications"></wa-icon>
  <wa-icon library="material" name="email"></wa-icon>
  <wa-icon library="material" name="delete"></wa-icon>
  <wa-icon library="material" name="volume_up"></wa-icon>
  <wa-icon library="material" name="settings"></wa-icon>
  <wa-icon library="material" name="shopping_basket"></wa-icon>
  <br />
  <wa-icon library="material" name="notifications_round"></wa-icon>
  <wa-icon library="material" name="email_round"></wa-icon>
  <wa-icon library="material" name="delete_round"></wa-icon>
  <wa-icon library="material" name="volume_up_round"></wa-icon>
  <wa-icon library="material" name="settings_round"></wa-icon>
  <wa-icon library="material" name="shopping_basket_round"></wa-icon>
  <br />
  <wa-icon library="material" name="notifications_sharp"></wa-icon>
  <wa-icon library="material" name="email_sharp"></wa-icon>
  <wa-icon library="material" name="delete_sharp"></wa-icon>
  <wa-icon library="material" name="volume_up_sharp"></wa-icon>
  <wa-icon library="material" name="settings_sharp"></wa-icon>
  <wa-icon library="material" name="shopping_basket_sharp"></wa-icon>
</div>

Remix Icon Jump to heading

This will register the Remix Icon library using the jsDelivr CDN. This library groups icons by categories, so the name must include the category and icon separated by a slash, as well as the -line or -fill suffix as needed. A mutator function is required to set the SVG's fill to currentColor.

Icons in this library are licensed under the Apache 2.0 License.

<script type="module">
  import { registerIconLibrary } from '/dist/webawesome.js';

  registerIconLibrary('remixicon', {
    resolver: name => {
      const match = name.match(/^(.*?)\/(.*?)?$/);
      match[1] = match[1].charAt(0).toUpperCase() + match[1].slice(1);
      return `https://cdn.jsdelivr.net/npm/[email protected]/icons/${match[1]}/${match[2]}.svg`;
    },
    mutator: svg => svg.setAttribute('fill', 'currentColor'),
  });
</script>

<div style="font-size: 24px;">
  <wa-icon library="remixicon" name="business/cloud-line"></wa-icon>
  <wa-icon library="remixicon" name="design/brush-line"></wa-icon>
  <wa-icon library="remixicon" name="business/pie-chart-line"></wa-icon>
  <wa-icon library="remixicon" name="development/bug-line"></wa-icon>
  <wa-icon library="remixicon" name="media/image-line"></wa-icon>
  <wa-icon library="remixicon" name="system/alert-line"></wa-icon>
  <br />
  <wa-icon library="remixicon" name="business/cloud-fill"></wa-icon>
  <wa-icon library="remixicon" name="design/brush-fill"></wa-icon>
  <wa-icon library="remixicon" name="business/pie-chart-fill"></wa-icon>
  <wa-icon library="remixicon" name="development/bug-fill"></wa-icon>
  <wa-icon library="remixicon" name="media/image-fill"></wa-icon>
  <wa-icon library="remixicon" name="system/alert-fill"></wa-icon>
</div>

Tabler Icons Jump to heading

This will register the Tabler Icons library using the jsDelivr CDN. This library features over 1,950 open source icons.

Icons in this library are licensed under the MIT License.

<script type="module">
  import { registerIconLibrary } from '/dist/webawesome.js';

  registerIconLibrary('tabler', {
    resolver: name => `https://cdn.jsdelivr.net/npm/@tabler/[email protected]/icons/${name}.svg`,
    mutator: svg => {
      svg.style.fill = 'none';
      svg.setAttribute('stroke', 'currentColor');
    },
  });
</script>

<div style="font-size: 24px;">
  <wa-icon library="tabler" name="alert-triangle"></wa-icon>
  <wa-icon library="tabler" name="arrow-back"></wa-icon>
  <wa-icon library="tabler" name="at"></wa-icon>
  <wa-icon library="tabler" name="ball-baseball"></wa-icon>
  <wa-icon library="tabler" name="cake"></wa-icon>
  <wa-icon library="tabler" name="files"></wa-icon>
  <br />
  <wa-icon library="tabler" name="keyboard"></wa-icon>
  <wa-icon library="tabler" name="moon"></wa-icon>
  <wa-icon library="tabler" name="pig"></wa-icon>
  <wa-icon library="tabler" name="printer"></wa-icon>
  <wa-icon library="tabler" name="ship"></wa-icon>
  <wa-icon library="tabler" name="toilet-paper"></wa-icon>
</div>

Unicons Jump to heading

This will register the Unicons library using the jsDelivr CDN. This library has two variations: line (default) and solid (*-s). A mutator function is required to set the SVG's fill to currentColor.

Icons in this library are licensed under the Apache 2.0 License. Some of the icons that appear on the Unicons website, particularly many of the solid variations, require a license and are therefore not available in the CDN.

<script type="module">
  import { registerIconLibrary } from '/dist/webawesome.js';

  registerIconLibrary('unicons', {
    resolver: name => {
      const match = name.match(/^(.*?)(-s)?$/);
      return `https://cdn.jsdelivr.net/npm/@iconscout/[email protected]/svg/${match[2] === '-s' ? 'solid' : 'line'}/${
        match[1]
      }.svg`;
    },
    mutator: svg => svg.setAttribute('fill', 'currentColor'),
  });
</script>

<div style="font-size: 24px;">
  <wa-icon library="unicons" name="clock"></wa-icon>
  <wa-icon library="unicons" name="graph-bar"></wa-icon>
  <wa-icon library="unicons" name="padlock"></wa-icon>
  <wa-icon library="unicons" name="polygon"></wa-icon>
  <wa-icon library="unicons" name="rocket"></wa-icon>
  <wa-icon library="unicons" name="star"></wa-icon>
  <br />
  <wa-icon library="unicons" name="clock-s"></wa-icon>
  <wa-icon library="unicons" name="graph-bar-s"></wa-icon>
  <wa-icon library="unicons" name="padlock-s"></wa-icon>
  <wa-icon library="unicons" name="polygon-s"></wa-icon>
  <wa-icon library="unicons" name="rocket-s"></wa-icon>
  <wa-icon library="unicons" name="star-s"></wa-icon>
</div>

Customizing the Default Library Jump to heading

The default icon library contains over 2,000 icons courtesy of Font Awesome. These are the icons that display when you use <wa-icon> without the library attribute. If you prefer to have these icons resolve elsewhere or to a different icon library, register an icon library using the default name and a custom resolver.

For example, this will change the default icon library to use Bootstrap Icons loaded from the jsDelivr CDN.

<script type="module">
  import { registerIconLibrary } from '/dist/webawesome.js';

  registerIconLibrary('default', {
    resolver: (name, family) => {
      const suffix = family === 'filled' ? '-fill' : '';
      return `https://cdn.jsdelivr.net/npm/[email protected]/icons/${name}${suffix}.svg`;
    },
  });
</script>

Customize the default library to use SVG sprites Jump to heading

To improve performance you can use a SVG sprites to avoid multiple trips for each SVG. The browser will load the sprite sheet once and then you reference the particular SVG within the sprite sheet using hash selector.

As always, make sure to benchmark these changes. When using HTTP/2, it may in fact be more bandwidth-friendly to use multiple small requests instead of 1 large sprite sheet.

When using sprite sheets, the wa-load and wa-error events will not fire.

For security reasons, browsers may apply the same-origin policy on <use> elements located in the <wa-icon> shadow DOM and may refuse to load a cross-origin URL. There is currently no defined way to set a cross-origin policy for <use> elements. For this reason, sprite sheets should only be used if you're self-hosting them.

<script type="module">
  import { registerIconLibrary } from '/dist/webawesome.js';

  registerIconLibrary('sprite', {
    resolver: name => `/assets/images/sprite.svg#${name}`,
    mutator: svg => svg.setAttribute('fill', 'currentColor'),
    spriteSheet: true,
  });
</script>

Customizing the System Library Jump to heading

The system library contains only the icons used internally by Web Awesome components. Unlike the default icon library, the system library does not rely on physical assets. Instead, its icons are hard-coded as data URIs into the resolver to ensure their availability.

If you want to change the icons Web Awesome uses internally, you can register an icon library using the system name and a custom resolver. If you choose to do this, it's your responsibility to provide all of the icons that are required by components. You can reference src/components/library.system.ts for a complete list of system icons used by Web Awesome.

<script type="module">
  import { registerIconLibrary } from '/dist/webawesome.js';

  registerIconLibrary('system', {
    resolver: name => `/path/to/custom/icons/${name}.svg`,
  });
</script>

Attributes & Properties Jump to heading

Learn more about attributes and properties.

Name	Description	Reflects
`name` `name`	The name of the icon to draw. Available names depend on the icon library being used. Type `string \| undefined`
`family` `family`	The family of icons to choose from. For Font Awesome Free, valid options include `classic` and `brands`. For Font Awesome Pro subscribers, valid options include, `classic`, `sharp`, `duotone`, `sharp-duotone`, and `brands`. A valid kit code must be present to show pro icons via CDN. You can set `<html data-fa-kit-code="...">` to provide one. Type `string`
`variant` `variant`	The name of the icon's variant. For Font Awesome, valid options include `thin`, `light`, `regular`, and `solid` for the `classic` and `sharp` families. Some variants require a Font Awesome Pro subscription. Custom icon libraries may or may not use this property. Type `string`
`autoWidth` `auto-width`	Sets the width of the icon to match the cropped SVG viewBox. This operates like the Font `fa-width-auto` class. Type `boolean` Default `false`
`swapOpacity` `swap-opacity`	Swaps the opacity of duotone icons. Type `boolean` Default `false`
`src` `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. Type `string \| undefined`
`label` `label`	An alternate description to use for assistive devices. If omitted, the icon will be considered presentational and ignored by assistive devices. Type `string` Default `''`
`library` `library`	The name of a registered custom icon library. Type `string` Default `'default'`

Events Jump to heading

Learn more about events.

Name	Description
`wa-load`	Emitted when the icon has loaded. When using `spriteSheet: true` this will not emit.
`wa-error`	Emitted when the icon fails to load due to an error. When using `spriteSheet: true` this will not emit.

CSS custom properties Jump to heading

Learn more about CSS custom properties.

Name	Description
`--primary-color`	Sets a duotone icon's primary color. Default `currentColor`
`--primary-opacity`	Sets a duotone icon's primary opacity. Default `1`
`--secondary-color`	Sets a duotone icon's secondary color. Default `currentColor`
`--secondary-opacity`	Sets a duotone icon's secondary opacity. Default `0.4`

CSS parts Jump to heading

Learn more about CSS parts.

Name	Description	CSS selector
`svg`	The internal SVG element.	`::part(svg)`
`use`	The `<use>` element generated when using `spriteSheet: true`	`::part(use)`

Importing Jump to heading

Autoloading components via projects is the recommended way to import components. If you prefer to do it manually, use one of the following code snippets.

CDN

npm

React

Let your project code do the work! Sign up for free to use a project with your very own CDN — it's the fastest and easiest way to use Web Awesome.

To manually import this component from NPM, use the following code.

import '@awesome.me/webawesome/dist/components/icon/icon.js';

To manually import this component from React, use the following code.

import WaIcon from '@awesome.me/webawesome/dist/react/icon';

Need a hand?

Report a bug

Ask for help

Getting Started

Resources

Components

Style Utilities

Layout

Patterns

Theming

Design Tokens

Terms & Policies

Web Awesome

Web Awesome Elsewhere

Icon

Examples Jump to heading

Families & Variants Jump to heading

Labels Jump to heading

Sizing Jump to heading

Auto Width Jump to heading

Colors Jump to heading

Duotone Jump to heading

Swap Duotone Opacity Jump to heading

Font Awesome Pro+ Jump to heading

Custom Icons Jump to heading

Icon Libraries Jump to heading

Bootstrap Icons Jump to heading

Boxicons Jump to heading

Lucide Jump to heading

Heroicons Jump to heading

Iconoir Jump to heading

Ionicons Jump to heading

Jam Icons Jump to heading

Material Icons Jump to heading

Remix Icon Jump to heading

Tabler Icons Jump to heading

Unicons Jump to heading

Customizing the Default Library Jump to heading

Customize the default library to use SVG sprites Jump to heading

Customizing the System Library Jump to heading

Attributes & Properties Jump to heading

Events Jump to heading

CSS custom properties Jump to heading

CSS parts Jump to heading

Importing Jump to heading

Get a lifetime discount on Web Awesome Pro!