PatternFly Elements - Home PatternFly Elements

Icon

Overview

PatternFly Icon component lazy-loads icons and allows custom icon sets

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 URL object that points to the icon's JavaScript module.

type getter = (set: string, icon: string) => URL
import { PfIcon } from '@patternfly/pf-icon';

// Or, in a non-module context:
// const PfIcon = await customElements.whenDefined('pf-icon');

PfIcon.addIconSet('local', (set, icon) =>
new URL(`/assets/icons/${set}-${icon}.js`));

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 new URL(`/icons/patternfly-custom/${icon}.js`, window.location.href);
// 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 arond 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.getIconURL = (set, icon) =>
new URL(`/icons/js/${set}/${icon}.js`, 'https://static.redhat.com');

To change the default set name, you can also override PfIcon.defaultIconSet

PfIcon.defaultIconSet = 'patternfly';

Now when <pf-icon> is used, it will automatically load icon modules from https://static.redhat.com/icons/js/patternfly/....

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

size

Size of the icon

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

Icon set

DOM Property
set
Type
unknown
Default
unknown
icon

Icon name

DOM Property
icon
Type
string
Default
''
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

None

CSS Shadow Parts

fallback

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

© 2022-2023 Red Hat, Inc. Deploys by Netlify