Icon
Icons are scalable vector symbols that represent actions, content, or status throughout your application. They support Font Awesome and custom icon libraries with animation presets.
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.
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 — drag the slider to see it in action.
Colors
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.
Families & Variants
A family sets an icon's overall style; a variant sets its weight. Set them with the family and variant attributes — family defaults to classic and variant to solid.
| Family | Variants | Plan | Preview |
|---|---|---|---|
classic
|
solid regular, light, thin |
Free |
|
brands |
— | Free |
|
duotone |
solid, regular, light, thin |
Pro |
|
sharp |
solid, regular, light, thin |
Pro |
|
sharp-duotone |
solid, regular, light, thin |
Pro |
|
light and thin variants, the sharp, duotone, and
sharp-duotone families, and the Pro+ packs require a Font Awesome Pro
plan. Provide a Kit code to unlock them.
Canvas
The canvas is the box an icon sits in. Choose one of four mutually exclusive modes with the canvas attribute (the default is fixed). It mirrors Font Awesome's icon canvas and scales with font-size, independent of sizing. The tinted box below shows each canvas's extent.
| Canvas | Box | Best For | Example |
|---|---|---|---|
fixed
|
1.25 × 1em |
Aligning icons in lists, menus, and toolbars |
|
auto |
auto × 1em |
Matching the icon's natural width |
|
square |
1.25 × 1.25em |
Standalone icons on a square footprint |
|
roomy |
1.5 × 1.5em |
Standalone icons that need more breathing room |
|
The auto-width attribute still works but is deprecated — prefer canvas="auto", which renders the same way.
Rotating & Flipping
Web Awesome supports Font Awesome's rotation and flip utilities for adjusting icon orientation. Use the rotate attribute to turn an icon by any number of degrees — not just the quarter-turns below — and the flip attribute to mirror it across the x, y, or both axes.
| Attribute | Value | Preview |
|---|---|---|
rotate |
90 |
|
rotate |
180 |
|
rotate |
270 |
|
flip |
x |
|
flip |
y |
|
flip |
both |
|
Rotate by any angle — and combine rotate and flip on the same icon:
Animating
Web Awesome supports Font Awesome's animation utilities for adding visual interest to icons. To select different types of animations, use the animation attribute when you reference an icon.
Every animation accepts the same timing controls — --animation-delay, --animation-direction, --animation-duration, --animation-iteration-count, and --animation-timing — plus the animation-specific custom properties shown in each example below. All animations respect prefers-reduced-motion (see Accessibility Considerations).
Beat
Use the beat animation to scale an icon up or down. This is useful for grabbing attention or for use with health/heart-centric icons.
Fade
Use the fade animation to fade an icon in and out visually to grab attention in a subtle (or not so subtle) way.
Beat-Fade
Use the beat-fade animation to grab attention by visually scaling and pulsing an icon in and out.
Bounce
Use the bounce animation to grab attention by visually bouncing an icon up and down.
Flip
Use the flip animation to rotate an icon in 3D space. By default, flip rotates an icon about the Y axis 180 degrees. Flipping is helpful for transitions, processing states, or for using physical objects that one flips in the real world.
Flip 360
Use the flip-360 animation to flip an icon all the way around in one smooth rotation — an extension of flip that gives it some extra oomph. It shares the same --flip-x, --flip-y, and --flip-z axis properties, plus --flip-angle, --flip-anticipation-scale, and --flip-overshoot.
Shake
Use the shake animation to grab attention or note that something is not allowed by shaking an icon back and forth.
Spin
Use the spin animation to get any icon to rotate, and use spin-pulse to have it rotate with eight steps. Use spin-reverse to rotate counter-clockwise. This works especially well with spinner and everything in the spinner icons category.
Spin Snap
Use spin-snap to rotate in distinct steps with a pause on each, like a clock's second hand. spin-snap-4 stops at four positions and spin-snap-8 at eight. Unlike spin-pulse — a continuous eight-step rotation — the snap animations ease into each stop. Add --animation-direction: reverse to any of them to run counter-clockwise.
Buzz
Use the buzz animation for a fast, tight vibration with rapid decay — quick attention without being loud, like a phone buzzing on a table or an expiring timer. Set --buzz-distance to control how far it travels.
Float
Use the float animation for a slow, drifting motion — great for empty states, subtle attention, and adding a bit of playful lightness. Adjust --float-height, --float-drift, and --float-tilt to shape the motion.
Jello
Use the jello animation for a playful jiggle — great for calling attention to something new, fun, or interactive. Set --jello-scale-x and --jello-scale-y to control how far it deforms.
Swing
Use the swing animation for a subtle dangle with a slow decay — great for things that physically dangle, like keys or a price tag. Set --swing-angle to control the peak rotation.
Wag
Use the wag animation, a cousin of swing, for a bottom-anchored wag — the top of the icon sways back and forth with a slow decay. Set --wag-angle to control the peak rotation.
Duotone
Duotone icons render on two layers — a primary and a secondary — that you can recolor and fade independently. By default both layers use currentColor, with the secondary layer at 40% opacity. These properties don't inherit, so set them directly on the icon.
| Property | Description | Default |
|---|---|---|
--primary-color |
Color of the primary (foreground) layer | currentColor |
--secondary-color |
Color of the secondary (background) layer | currentColor |
--primary-opacity |
Opacity of the primary layer | 1 |
--secondary-opacity |
Opacity of the secondary layer | 0.4 |
swap-opacity |
Attribute that swaps the primary and secondary opacities | false |
Swap Duotone Opacity
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.
Font Awesome Pro+ Icons
If you're a Font Awesome Pro+ customer, you have access to whole packs of distinctive icons. Set the pack's family and variant like any other icon.
| Pack | Family | Variant | Preview |
|---|---|---|---|
| Chisel | chisel |
regular |
|
| Etch | etch |
solid |
|
| Graphite | graphite |
thin |
|
| Jelly | jelly, jelly-duo, jelly-fill |
regular |
|
| Mosaic | mosaic |
solid |
|
| Notdog | notdog, notdog-duo |
solid |
|
| Pixel | pixel |
regular |
|
| Slab | slab, slab-press, slab-duo, slab-press-duo |
regular |
|
| Thumbprint | thumbprint |
light |
|
| Utility | utility, utility-duo, utility-fill |
semibold |
|
| Vellum | vellum |
solid |
|
| Whiteboard | whiteboard |
semibold |
|
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.
Self-Hosting the Default Library
By default, icons are loaded from the Font Awesome CDN. If you'd prefer to download the icons and serve them from your own server, you can use the setIconPath() function to point the default icon library at your self-hosted directory.
When you download Font Awesome, the archive will contain an svgs directory with subfolders such as solid/, regular/, brands/, etc. Copy the svgs directory (or its contents) into your project and set the icon path to point to it.
<script type="module"> import { setIconPath } from '/dist/webawesome.js'; // Point to the `svgs` directory from your Font Awesome download setIconPath('/assets/fontawesome/svgs'); </script>
After calling setIconPath(), icons will resolve to your self-hosted directory instead of the CDN. For example, <wa-icon name="house"> will load from /assets/fontawesome/svgs/solid/house.svg.
For more control over how icon URLs are constructed, you can use the getIconFolder() helper along with registerIconLibrary() to build a custom resolver. The getIconFolder() function maps a family and variant to the correct folder name, so you don't have to replicate that logic yourself.
<script type="module"> import { getIconFolder, registerIconLibrary } from '/dist/webawesome.js'; registerIconLibrary('default', { resolver: (name, family, variant) => { const folder = getIconFolder(name, family, variant); return `/assets/fontawesome/svgs/${folder}/${name}.svg?v=2`; }, }); </script>
setIconPath() must be called before Web Awesome components are loaded, similar to setBasePath() and setKitCode().
Customizing the Default Library
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/bootstrap-icons@1.13.1/icons/${name}${suffix}.svg`; }, }); </script>
Customize the Default Library to Use SVG Sprites
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
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>
Third-Party Icon Libraries
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.
Sizing, colors, the canvas, rotating and flipping, and animations work with icons from any library — they're applied to the <wa-icon> host, so they don't depend on where the icon comes from. (Only the duotone color properties are specific to Font Awesome's duotone icons.)
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
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.
Boxicons
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.
Lucide
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.
Heroicons
This will register the Heroicons library using the jsDelivr CDN.
Icons in this library are licensed under the MIT License.
Iconoir
This will register the Iconoir library using the jsDelivr CDN.
Icons in this library are licensed under the MIT License.
Ionicons
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.
Jam Icons
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.
Material Icons
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.
Remix Icon
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.
Tabler Icons
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.
Unicons
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.
Accessibility Considerations
Web Awesome hides an unlabeled <wa-icon> from assistive devices, so an icon is presentational unless you give it a name. The two things to get right are labeling icons that carry meaning and respecting users who prefer less motion.
Labeling Icons
Give an icon a label when it carries meaning on its own — when it's the only content of a control, or conveys status. Omit it when nearby text already says the same; unlabeled icons are hidden from assistive devices.
| Scenario | Label? | In Context | Why |
|---|---|---|---|
| Icon-only control | Yes |
|
The icon is the button's only content, so the label gives it an accessible name. |
| Status icon | Yes |
|
The icon conveys status the nearby text doesn't. |
| Icon beside its own text | No |
|
The visible “Share” text already names the action; a label would be announced twice. |
| Decorative | No |
|
It only decorates text that already carries the meaning. |
Set the label attribute to the text a screen reader should announce:
Reduced Motion
All icon animations honor the user's prefers-reduced-motion setting — when it's set to reduce, Web Awesome disables them automatically so motion never becomes a barrier. See Font Awesome's animation accessibility notes for more.
Importing
If you're using the autoloader or a hosted project, components load on demand — no manual import needed. To cherry-pick a component manually, use one of the following snippets.
Import this component directly from the CDN:
import 'https://ka-f.webawesome.com/webawesome@0.17.0/components/icon/icon.js';
After installing Web Awesome via npm, import this component:
import '@awesome.me/webawesome/dist/components/icon/icon.js';
If you're self-hosting Web Awesome, import this component from your server:
import './webawesome/dist/components/icon/icon.js';
To import this component for React 18 or below, use the following code:
import WaIcon from '@awesome.me/webawesome/dist/react/icon/index.js';
Attributes & Properties
Learn more about attributes and properties.
| Name | Description | Reflects |
|---|---|---|
animationanimation |
Sets the animation for the icon
Type
IconAnimation | undefined
|
|
autoWidthauto-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
|
|
canvascanvas |
Sets the icon canvas — the box the icon is centered within. Unset renders as
fixed (1.25em × 1em); auto hugs the
icon's width; square is 1.25em × 1.25em; roomy is 1.5em × 1.5em. Mirrors Font Awesome's fa-fixed-width,
fa-width-auto, fa-canvas-square, and fa-canvas-roomy. Scales with font-size.
Type
IconCanvas | undefined
|
|
familyfamily |
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
|
|
flipflip |
Sets the flip direction of the icon along the 'x' (horizontal), 'y' (vertical), or 'both' axes.
Type
'x' | 'y' | 'both' | undefined
|
|
labellabel |
An alternate description to use for assistive devices. If omitted, the icon will be considered presentational and
ignored by assistive devices.
Type
string
Default
''
|
|
librarylibrary |
The name of a registered custom icon library.
Type
string
Default
'default'
|
|
namename |
The name of the icon to draw. Available names depend on the icon library being used.
Type
string | undefined
|
|
rotaterotate |
Sets the rotation degree of the icon
Type
number
Default
0
|
|
srcsrc |
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
|
|
swapOpacityswap-opacity |
Swaps the opacity of duotone icons.
Type
boolean
Default
false
|
|
variantvariant |
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
|
|
Events
Learn more about events.
| Name | Description |
|---|---|
wa-error |
Emitted when the icon fails to load due to an error. When using spriteSheet: true this will not emit. |
wa-load |
Emitted when the icon has loaded. When using spriteSheet: true this will not emit. |
CSS Custom Properties
Learn more about CSS custom properties.
| Name | Description |
|---|---|
--animation-delay |
Sets when the animation will start.
Default
0
|
--animation-direction |
Defines whether or not the animation should play in reverse on alternate cycles.
Default
normal
|
--animation-duration |
Defines the length of time that an animation takes to complete one cycle.
Default
1s
|
--animation-iteration-count |
Defines the number of times an animation cycle is played.
Default
infinite
|
--animation-timing |
Describes how the animation will progress over one cycle of its duration.
|
--beat-fade-opacity |
Set lowest opacity value an icon with
beat-fade animation will fade to and from. |
--beat-fade-scale |
Set max value that an icon with
beat-fade animation will scale. |
--beat-scale |
Set the scale multiplier for an icon with
beat animation. This multiplies the animation's 1.25× base pulse, so the default 1.25 peaks at ~1.56× and 2 roughly doubles the pulse. |
--bounce-anticipation |
Set the downward squash distance before an icon with
bounce animation jumps. |
--bounce-height |
Set the max height an icon with
bounce animation will jump to when bouncing. |
--bounce-jump-scale-x |
Set the icon’s horizontal distortion (“squish”) at the top of the jump.
|
--bounce-jump-scale-y |
Set the icon’s vertical distortion (“squish”) at the top of the jump.
|
--bounce-land-scale-x |
Set the icon’s horizontal distortion (“squish”) when landing after the jump.
|
--bounce-land-scale-y |
Set the icon’s vertical distortion (“squish”) when landing after the jump.
|
--bounce-rebound |
Set the amount of rebound an icon with
bounce animation has when landing after the jump. |
--bounce-start-scale-x |
Set the icon’s horizontal distortion (“squish”) when starting to bounce.
|
--bounce-start-scale-y |
Set the icon’s vertical distortion (“squish”) when starting to bounce.
|
--buzz-distance |
Set the horizontal travel of an icon with
buzz animation. |
--fade-opacity |
Set lowest opacity value an icon with
fade animation will fade to and from. |
--flip-angle |
Set rotation angle of flip for an icon with
flip or flip-360 animation. A positive angle denotes a clockwise rotation, a negative angle a counter-clockwise one. |
--flip-anticipation-scale |
Set the scale of the wind-up before an icon with
flip or flip-360 animation rotates. |
--flip-overshoot |
Set how far past the final angle an icon with
flip or flip-360 animation rotates before settling. |
--flip-x |
Set x-coordinate of the vector denoting the axis of rotation (between 0 and 1) for an icon with
flip or flip-360 animation. |
--flip-y |
Set y-coordinate of the vector denoting the axis of rotation (between 0 and 1) for an icon with
flip or flip-360 animation. |
--flip-z |
Set z-coordinate of the vector denoting the axis of rotation (between 0 and 1) for an icon with
flip or flip-360 animation. |
--float-drift |
Set the horizontal drift of an icon with
float animation. |
--float-height |
Set the rise height of an icon with
float animation. |
--float-squash-x |
Set the horizontal squash of an icon with
float animation at rest. |
--float-squash-y |
Set the vertical squash of an icon with
float animation at rest. |
--float-stretch-x |
Set the horizontal stretch of an icon with
float animation at its peak. |
--float-stretch-y |
Set the vertical stretch of an icon with
float animation at its peak. |
--float-tilt |
Set the rotation of an icon with
float animation. |
--jello-scale-x |
Set the horizontal stretch of an icon with
jello animation. |
--jello-scale-y |
Set the vertical stretch of an icon with
jello animation. |
--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
|
--swing-angle |
Set the peak rotation of an icon with
swing animation. |
--wag-angle |
Set the peak rotation of an icon with
wag animation. |
CSS Parts
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)
|