Icon

Installation

We recommend loading elements via a CDN such as JSPM and using an import map to manage your dependencies.

For more information on import maps and how to use them, see the import map reference on MDN Web Docs.

If you are using node and NPM, you can install this component using npm:

npm install @patternfly/elements

Then import this component into your project by using a bare module specifier:

import '@patternfly/elements/pf-icon/pf-icon.js';

Please Note You should either load elements via a CDN or install them locally through NPM. Do not do both.

Installation

npm install @patternfly/elements

Usage

Place the icon element on the page and give it an icon name from the [default icon set][icon-sets]. In most cases, the icon should be labelled using aria-label or aria-labelledby, or removed from the accessibility tree with aria-hidden="true" or role="presentation", if its content is merely presentational and expressed using accessible text copy elsewhere.

<pf-icon icon="user" aria-label="user"></pf-icon>
<pf-icon icon="lock" aria-label="lock"></pf-icon>
<pf-icon icon="laptop" aria-label="laptop"></pf-icon>
<pf-icon icon="cloud" aria-label="cloud"></pf-icon>

Size

The default size is 1em, so icon size matches text size. 2x, etc, are multiples of font size. sm, md, etc are fixed pixel-based sizes.

<pf-icon icon="user" size="sm"></pf-icon>
<pf-icon icon="user" size="md"></pf-icon>
<pf-icon icon="user" size="lg"></pf-icon>
<pf-icon icon="user" size="xl"></pf-icon>

Icon sets

Icon comes with three built-in icon sets:

1. fas: Font Awesome Free Solid icons (the default set)
2. far: Font Awesome Free Regular icons
3. patternfly: PatternFly icons

Use the set attribute to pick an alternative icon set.

<pf-icon icon="star"    set="far"></pf-icon>
<pf-icon icon="redhat"  set="fab"></pf-icon>
<pf-icon icon="package" set="patternfly"></pf-icon>

Register a New Icon Set

Icons are JavaScript module which export a lit renderable, typically an inline SVG element template literal tagged with the Lit svg template tag. To register a new icon set, call the static addIconSet method with the set name and a getter function. The getter function takes the icon set and icon name and returns a promise containing the icon node, or any other renderable value.

type IconResolveFunction = (set: string, icon: string) => Promise<Node> | Node;

import { PfIcon } from '@patternfly/pf-icon';
// Or, in a non-module context:
// const PfIcon = await customElements.whenDefined('pf-icon');
PfIcon.addIconSet('local', (set, icon) =>
import(</span><span class="token string">/assets/icons/</span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span><span class="token keyword">set</span><span class="token interpolation-punctuation punctuation">}</span></span><span class="token string">-</span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>icon<span class="token interpolation-punctuation punctuation">}</span></span><span class="token string">.js</span><span class="token template-punctuation string">))
.then(mod => mod.default);

Updating an Existing Icon Set

To updating an existing icon set, you use the same addIconSet function. By defaulting back to then existing getIconUrl method, you you can add a new icon to an existing set:

PfIcon.addIconSet('patternfly', (set, icon) => {
  switch (icon) {
    // add your custom icons
    case 'my-custom-icon':
    case 'other-custom-icon':
return import(`/icon-overrides/patternfly-custom/${icon}.js`)
  .then(mod => mod.default);
    // fall back to built-in icons
    default:
return PfIcon.getIconUrl(set, icon);
  }
});

Override the Default Icon Sets

Icons are loaded lazily by default, so there's no performance penalty for keeping the default icon sets around and unused. However, if you'd like to override the default icon sets across the entire page, you can use addIconSet with the fas, far, and patternfly set names:

import { PfIcon } from '@patternfly/pf-icon';
PfIcon.resolve = (set, icon) =>
import(</span><span class="token string">/icons/</span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span><span class="token keyword">set</span><span class="token interpolation-punctuation punctuation">}</span></span><span class="token string">-</span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>icon<span class="token interpolation-punctuation punctuation">}</span></span><span class="token string">.js</span><span class="token template-punctuation string">))
.then(mod => mod.default);

Now when <pf-icon> is loaded from the RedHat DX CDN, it will automatically load icon modules from the CDN as well.

Loading

Icons load lazily by default, meaning that the browser will not attempt to fetch and render the icon until it scrolls into view. You can change this with the loading attribute, which has three values:

1. lazy (the default): load icons when they scroll into view
2. idle: load each icon on the page as soon as the browser enters an idle state Or, on less-capable browsers, at the next frame
3. eager: each icon will begin to load and render the moment it connects to the DOM.

You might choose to enable eager rendering for "above-the-fold" content, but keep lazy loading for the rest of the page.

<header>
  <h1>
    <pf-icon icon="fire" loading="eager"></pf-icon>
    Hot News!
  </h1>
</header>
<main>
<article>...</article>
</main>
<footer>
<h2>
<pf-icon icon="phone"></pf-icon>
Contact Us
</h2>
...
</footer>