Polarity Integration Component Library

Icon Component

Renders FontAwesome SVG icons with named sizes, semantic colors, and optional spin animation.

Installation

npm install @polarityio/pi-icon

Peer Dependencies

• lit ^3.0.0

Usage

import '@polarityio/pi-icon';
import { faStar, faShieldHalved, faSpinner, faBell } from '@polarityio/pi-icon';

Basic Icon

import { html } from 'lit';
import { faStar } from '@fortawesome/free-solid-svg-icons';

html`<pi-icon .icon=${faStar}></pi-icon>`;

Sized and Colored Icon

import { html } from 'lit';
import { faShieldHalved } from '@fortawesome/free-solid-svg-icons';

html`<pi-icon .icon=${faShieldHalved} size="lg" color="success"></pi-icon>`;

Spinning Icon

import { html } from 'lit';
import { faSpinner } from '@fortawesome/free-solid-svg-icons';

html`<pi-icon .icon=${faSpinner} spin></pi-icon>`;

Accessible Icon with Label

import { html } from 'lit';
import { faBell } from '@fortawesome/free-solid-svg-icons';

html`<pi-icon .icon=${faBell} label="Notifications"></pi-icon>`;

Icons Export

The package re-exports all FontAwesome Free Solid SVG icons from @fortawesome/free-solid-svg-icons:

import { faStar, faUser, faGear, faBell } from '@polarityio/pi-icon';

This is a convenience re-export — you can import any icon from the FontAwesome Free Solid set directly through this package.

API Reference

Properties

| Property | Type | Default | Description | | ----------- | ------------------------------------------------------------------------------------------------------------------------------ | ----------- | ----------------------------------------------------------------------------------------------- | | icon | IconDefinition \| undefined | undefined | The FontAwesome icon definition to render. | | size | 'xs' \| 'sm' \| 'base' \| 'lg' \| 'xl' \| '2xl' \| undefined | undefined | Named size of the icon. | | color | 'primary' \| 'secondary' \| 'success' \| 'warning' \| 'danger' \| 'info' \| 'urgent' \| 'inverse' \| 'disabled' \| undefined | undefined | Semantic color variant. | | label | string \| undefined | undefined | Accessible label for screen readers. When set, the icon gets role="img". | | spin | boolean | false | Enables continuous rotation animation. Reflected to attribute. | | spinSpeed | string \| undefined | undefined | CSS time value for animation duration (e.g., '0.5s', '2s'). Set via spin-speed attribute. |

CSS Custom Properties

| Property | Default | Description | | ---------------------- | -------------- | ---------------------------------- | | --pi-icon-size | 16px | Override the default icon size. | | --pi-icon-color | currentColor | Override the icon color. | | --pi-icon-spin-speed | 2s | Override the spin animation speed. | | --pi-icon-size-xs | 12px | Size for size="xs". | | --pi-icon-size-sm | 14px | Size for size="sm". | | --pi-icon-size-base | 16px | Size for size="base". | | --pi-icon-size-lg | 20px | Size for size="lg". | | --pi-icon-size-xl | 24px | Size for size="xl". | | --pi-icon-size-2xl | 32px | Size for size="2xl". |

Color Token Mapping

When using the color property, the icon color is set via the corresponding design token:

| Color Value | CSS Token Used | | ----------- | --------------------------- | | primary | --pi-color-font-primary | | secondary | --pi-color-font-secondary | | success | --pi-color-font-success | | warning | --pi-color-font-warning | | danger | --pi-color-font-danger | | info | --pi-color-font-info | | urgent | --pi-color-font-urgent | | inverse | --pi-color-font-inverse | | disabled | --pi-color-font-disabled |

Accessibility

• When no label is provided, the icon is decorative: role="presentation" and aria-hidden="true".
• When label is provided, the icon is semantic: role="img" and aria-label is set.

Theming

Customize the appearance using CSS custom properties. This component uses design tokens from @polarityio/pi-shared for consistent theming across the component library.

License

MIT