HyIcon

A flexible, SSR-safe icon component that renders SVG icons from registered icon sets.

Icon Sets

All icons are opt-in via @whitespaceux/harmony-icons. Two import levels per library:

• System — import '@whitespaceux/harmony-icons/mdi/system' — 44 component-internal icons
• Full — import '@whitespaceux/harmony-icons/mdi' — all ~884 portable icons
• Individual — import '@whitespaceux/harmony-icons/mdi/home' — one icon

Available libraries: mdi (Material Design Icons), lucide, bi (Bootstrap Icons). All icons are portable — guaranteed to work across all libraries. Swap libraries by changing the import path. Zero markup changes.

Theming

Icons inherit color from their parent via currentColor. Parent components can override icon color by setting --hy-icon-color on their :host element.

Important: --hy-icon-color must be set on :host, not on .base or shadow DOM elements. Slotted icons live in light DOM and only inherit custom properties from the host.

For the common case "this icon means danger/warning/success/…", use the variant property instead of writing --hy-icon-color by hand. variant writes the matching semantic foreground token into --hy-icon-color on the host; an externally-set --hy-icon-color (inline, class, or parent-component cascade with higher specificity) still wins.

Sizes

Size	Pixels	Use case
sm	10px	Badges, dense layouts
md	16px	Standard (default)
lg	20px	Buttons, UI elements
xl	24px	Headers
2xl	32px	Hero sections

Accessibility

Unlabelled icons are decorative by default: without a label, the icon is hidden from screen readers (the raw icon name is never announced). Give informative icons a label to expose them as role="img" with that name.

Examples

Basic usage (decorative — hidden from screen readers)

<hy-icon name="close"></hy-icon>

With size and accessibility

<hy-icon name="close" size="lg" label="Close dialog" tooltip="Close this dialog"> </hy-icon>

Decorative icon (hidden from screen readers)

<hy-icon name="check" decorative></hy-icon>

Semantic color variant

<hy-icon name="alert-circle-outline" variant="danger"></hy-icon>
<hy-icon name="check" variant="success"></hy-icon>

Methods

registerSet()

Register a complete icon set. Icons are SVG strings keyed by name.

Parameters:

• name - The name for this icon set
• icons - A flat map of icon name to SVG string

registerIcon()

Register a single icon into an existing (or new) set.

Parameters:

• set - The icon set name
• name - The icon name
• svg - The SVG string

hasIcon()

Check if an icon exists in a set.

Parameters:

• set - The icon set name
• name - The icon name

firstUpdated()

Called after the first update completes. Sets initial host attributes for styling via CSS attribute selectors.

willUpdate()

Called before each update to sync host attributes with property changes. Ensures attributes stay in sync when set, name, or size properties change.