Skip to content
Versions v3 v2 v1

Icon

An icon component is a container that allows for icons of varying dimensions to seamlessly replace each other without shifting surrounding content.

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.

Overview

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.

View HTML Source
<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.

View HTML Source
<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>

Slots

If you wish to display some content while the icon loads (or while JS is disabled), you can slot it into <pf-icon>. For instance, when using a checkmark icon in a server status table, you may wish to display a checkmark emoji if JS is disabled.

<pf-icon icon="check"></pf-icon>

It's recommended to use the icon name in the default slot, or aria-label(ledby) so that the icon is accessible to screen readers.

<pf-icon icon="check">check</pf-icon>
Default Slot

Slotted content is used as a fallback in case the icon doesn't load

Attributes

set

Icon set

DOM Property
set
Type
string
Default
'fas'
icon

Icon name

DOM Property
icon
Type
string
Default
''
size

Size of the icon

DOM Property
size
Type
'sm' | 'md' | 'lg' | 'xl'
Default
'sm'
loading

Controls how eager the element will be to load the icon data

  • eager: eagerly load the icon, blocking the main thread
  • idle: wait for the browser to attain an idle state before loading
  • lazy (default): wait for the element to enter the viewport before loading
DOM Property
loading
Type
'idle' | 'lazy' | 'eager' | undefined
Default
'lazy'

DOM Properties

None

Methods

None

Events

load

Fired when an icon is loaded and rendered

Event Type:
Event
error

Fired when an icon fails to load

Event Type:
unknown

CSS Custom Properties

CSS Property Description Default
--pf-icon--size

size of the icon

CSS Shadow Parts

fallback

Container for the fallback (i.e. slotted) content

© 2018-2024 Red Hat, Inc. Deploys by Netlify