HyIcon

Usage examples on this page are written for Lit / plain HTML (<hy-icon>). The same component ships as HyIcon in @whitespaceux/harmony-react (native React 19), with typed wrappers for Angular, Solid, Svelte, and Vue. The API reference below applies to all frameworks.

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.

Colour contract for registered SVGs. A fill / stroke attribute is monochrome ink: the component repaints it to currentColor at render time (on the root <svg> and on every descendant), so a raw export with a baked fill="#1A73E8" follows the theme, --hy-icon-color, variant and forced-colors like any stock icon. none / transparent are respected and fills inside <mask> are left alone. A stroke icon without its own stroke-width renders at SVG's default 1px. An inline style="fill: …" is fixed artwork and is never touched — that is the opt-out for a brand mark.

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>

API

Properties

Property	Attribute	Type	Default	Description
name	name	string	''	The name of the icon to display. Must exist in the selected icon set.
set	set	IconSetName | undefined	undefined	Per-instance icon set override. When unset, the icon resolves its set from the inherited --hy-icon-set CSS custom property (which cascades across shadow boundaries), then falls back to the global HyIcon.defaultSet.
size	size	'sm' | 'md' | 'lg' | 'xl' | '2xl'	'md'	Predefined size for the icon with symmetric scaling around the base md size (16px).
variant	variant	'neutral' | 'brand' | 'success' | 'warning' | 'danger' | 'info' | 'subtle' | 'inverse'	'neutral'	Semantic color variant. neutral (default) keeps the inherited cascade so parent components (button, chip, list, etc.) that set --hy-icon-color still drive the color. Any other value writes the matching --hy-foreground-*-rest token into --hy-icon-color on this host, which consumers can still override externally (inline style, class, or higher-specificity cascade).
label	label	string | undefined	—	Accessible label for the icon. When set, the icon is exposed to screen readers as an image with this name. When omitted, the icon is treated as decorative (hidden from screen readers) — the raw registry name is never announced. Ignored when decorative is true.
decorative	decorative	boolean	false	Explicitly marks the icon as purely decorative, hiding it from screen readers (aria-hidden="true", no role="img"). Unlabelled icons are already treated as decorative; set this to make the intent explicit, or to suppress a label that only sighted users should get via tooltip.
tooltip	tooltip	string | undefined	—	Tooltip text shown on hover for additional context.

CSS Parts

Part	Description
base	The wrapper <span> around the SVG content.
error	Applied alongside base when the icon fails to resolve (invalid name).

CSS Custom Properties

Property	Description
--hy-icon-color	Override icon color from parent components. Set on :host, not .base. Falls back to --hy-foreground-default-rest. Reaches every fill / stroke attribute in the SVG, which the component repaints to currentColor (none respected; an inline style is the opt-out).
--hy-icon-set	Override the active icon library for a subtree (cascades across shadow boundaries). Resolution: set prop, then this property, then HyIcon.defaultSet. One portable name resolves to the chosen library's glyph.

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