# `lr-icon` - **Import** `import '@aceshooting/lyra-ui/components/lr-icon.js';` (stable tag alias; registers the tag) - **Class** `LyraIcon`, also available unregistered from `@aceshooting/lyra-ui/components/utility/icon/icon.class.js` - **Family** `components/utility/` — see `llms/index.md` for its siblings - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md` - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt) - **Deprecated property** `autoWidth` / `auto-width` since `8.0.0`; use property `canvas="auto"`; removal not before `10.0.0` — autoWidth is a boolean compatibility spelling that cannot express fixed canvas sizes; canvas covers both automatic and explicit sizing. That version is a policy floor, not a plan: `wa-icon` still publishes its own deprecated `auto-width` attribute, so this alias is removed only when upstream's is. - **Optional peers** `dompurify` — see `llms/peers.md` - **Themeable via** 4 parts, 45 custom properties — see this component's own `@csspart`/`@cssprop` list below - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md` --- ## `lr-icon` SVG icon primitive. Left alone it is dependency-free and offline: a built-in path, no icon font, no sprite sheet, no network access at all. **New in 8.0.0**, it can also resolve a name through a registered icon library, or fetch a single SVG document from `src` — those paths do hit the network, and every byte they return is capped, sanitized, and rendered only if the whole pipeline succeeds. Pairs with `lr-icon-button` (see `llms/components/lr-icon-button.md`). **Properties:** - `name: string = ''` (reflected once set) — a built-in glyph: `add`, `check`, `close`, `search`, `menu`, `chevron-left`, `chevron-right`, `chevron-down`, `calendar`, `command`, `trash`. An unknown name renders nothing (no error, no fallback glyph). With a registered `library`, this is instead the name handed to that library's resolver. The setter accepts `undefined` to clear the name; reads remain the canonical non-nullable `''`. - `path: string = ''` — raw SVG path data for a glyph the built-in set doesn't cover. Takes precedence over `name`. - `label: string = ''` — accessible name. Left empty (the default) the stable semantic owner is `aria-hidden="true"`, which is what you want whenever adjacent text already names the control. A host `aria-label` wins over it. For a labeled remote icon the same semantic owner and name remain present through idle, loading, loaded, empty, and error states without double-naming the SVG. - `library: string = 'default'` (reflected) — name of a library registered with `registerIconLibrary()`. `default` means the built-in glyph set. An **unregistered** name also falls back to the built-in set instead of erroring, which is what lets registration happen after first render. - `family: string = ''` and `variant: string = ''` (reflected once set) — forwarded with `name` to a registered library resolver. Their vocabulary belongs to that library; for example, an icon host might distinguish `classic`/`sharp` families and `regular`/`solid` variants. - `src: string = ''` — URL of a single SVG document to fetch. It applies only when no registered library owns the icon: no `library` set, an unregistered one, or an empty `name`. Once a registered library does own the name it decides alone — a resolver that returns `''` or throws does **not** fall back to `src`. Assigning `undefined` aborts and clears any pending remote load, removes the source, and reads back as `''`. - `rotate: number = 0` (reflected once changed) — clockwise rotation in degrees, applied to the icon box. At zero there is no `transform` at all, so an ordinary icon never becomes a containing block; a non-finite value leaves the icon unrotated. - `flip?: 'x' | 'y' | 'both' | 'horizontal' | 'vertical'` (reflected, type `LyraIconFlip`) — mirrors the icon about the vertical, horizontal, or both axes. `horizontal`/`vertical` are retained Lyra aliases for the mirrored `x`/`y` vocabulary. Unset by default. - `canvas?: 'fixed' | 'auto' | 'square' | 'roomy'` (reflected, type `LyraIconCanvas`) — sizes the layout box. Unset behaves as `fixed` (1.25em × 1em); `auto` follows the SVG's intrinsic width at 1em high; `square` is 1.25em × 1.25em; `roomy` is 1.5em × 1.5em. All scale with `font-size`. - `autoWidth: boolean = false` (attribute `auto-width`, reflected, deprecated) — compatibility alias for `canvas="auto"`; an explicit `canvas` wins. - `swapOpacity: boolean = false` (attribute `swap-opacity`, reflected) — swaps the primary and secondary opacity hooks on SVGs that carry `.fa-primary`/`.fa-secondary` duotone layers. - `animation?: LyraIconAnimation` (reflected) — one of `beat`, `fade`, `beat-fade`, `bounce`, `flip`, `flip-360`, `shake`, `spin`, `spin-pulse`, `spin-reverse`, `spin-snap`, `spin-snap-4`, `spin-snap-8`, `buzz`, `wag`, `float`, `swing`, or `jello`. Every treatment stops under `prefers-reduced-motion: reduce`. - `fixedWidth: boolean = false` (attribute `fixed-width`, reflected) — widens the icon _box_ to `--lr-icon-fixed-width` while the glyph keeps `--lr-icon-size` and centres inside it, so a column of differently-shaped icons lines its labels up. **Events:** - `lr-load` (`detail: { src: string }`) — a remote icon finished loading and is in the DOM. Also fires for a valid-but-empty document, which is not a failure. Never fires for a built-in glyph. - `lr-error` (`detail: { src: string; error: unknown }`) — a remote icon could not be resolved, fetched, size-capped, sanitized, or parsed as an SVG document. `src` is the URL that was attempted (or the icon name, when a library resolver itself threw). **Slots:** (default) — custom SVG geometry, rendered only when neither `path` nor a known `name` resolves **and** no remote source is configured; a fetched document is never merged with slotted nodes. Slotted nodes are cloned into the component-owned `