Icon
Render trusted SVG icons with accessible decorative and meaningful states.
Use the component directly. Named icons resolve against Lucide by default via provideKikitaUi(); register your own set with provideKuiIcons() to override or opt out entirely.
import { KuiIconComponent } from '@kikita-labs/ui';Use labels only when the icon carries meaning; omit labels for decorative support icons. Size with named presets or CSS lengths.
<div class="basic-icon-example">
<span class="basic-icon-example__status">
<kui-icon [source]="checkIcon" label="Success" size="18px" />
Package verified
</span>
<button kuiIconButton type="button" shape="soft" aria-label="Run magic action">
<kui-icon [source]="sparkIcon" />
</button>
</div>Override the resolved icon set anywhere in the tree with provideKuiIcons() in a component's own providers; later registrations win for names they both define.
<div class="swap-icon-set-example">
<div class="swap-icon-set-example__item">
<kui-icon name="star" label="Lucide star" size="28px" />
<span>Lucide (default)</span>
</div>
<div class="swap-icon-set-example__item">
<app-material-icon-scope />
<span>Material Symbols</span>
</div>
<div class="swap-icon-set-example__item">
<app-custom-icon-scope />
<span>Custom set</span>
</div>
</div>Inline SVG inputs are trusted-code APIs, not user-content APIs.
- Register SVG strings from static application code with
provideKuiIcons(). - Pass only trusted static SVG to
[source]. - Do not pass user-generated SVG markup into the registry or direct source input.
- Use
srcfor normal image URLs when you do not need inline SVG styling. - The default Lucide resolver fetches SVG markup from the jsDelivr CDN by name; set
provideKikitaUi({ icons: false })to avoid that network dependency, or override with your own registry.
Inputs and provider API verified against @kikita-labs/ui v1.6.1 public typings.
| Name | Type | Default | Description |
|---|---|---|---|
| kui-icon | Component | - | Renders an icon from a registered name, trusted inline SVG source, or image URL. |
| name | KuiIconName | undefined | undefined | Icon name resolved from icons registered with provideKuiIcons(), falling back to the default Lucide resolver unless disabled. |
| source | KuiIconSource | undefined | undefined | Trusted static inline SVG markup. It takes precedence over name. |
| src | string | undefined | undefined | External image URL used when no source or registered name is provided. |
| label | string | undefined | undefined | Accessible name for meaningful icons. Omit it for decorative icons. |
| size | '2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | string | number | '1em' | Named presets map to Kikita icon-size tokens. Numeric values become pixels, and arbitrary CSS size strings pass through. |
| provideKuiIcons(icons) | EnvironmentProviders | - | Registers a static map of trusted SVG strings, or an async KuiIconResolver function, for name-based icon lookup. Later registrations take precedence for names both define. Route-level only; component providers cannot accept EnvironmentProviders. |
| KUI_ICONS | InjectionToken<readonly KuiIconRegistry[]> | - | The multi-provider token behind provideKuiIcons(). Provide it directly in a component's own providers ({ provide: KUI_ICONS, multi: true, useValue }) to scope an icon-set override to that subtree. |
| provideKikitaUi({ icons }) | 'lucide' | false | 'lucide' | Registers kui-icon's default resolvers: Lucide (lazily fetched SVG markup from the jsDelivr CDN) and the built-in KUI_BRAND_ICONS set (currently just the 'kikita-brand' wordmark, resolved locally). Set to false to opt out of both. |
Icon accessibility depends on whether the graphic adds information.
- Omit
labelfor decorative icons so they are hidden from assistive technology. - Provide
labelwhen the icon itself communicates status, action, or identity. - Prefer visible text next to icons for actions; icon-only buttons need an accessible name.
- Keep icon sizing proportional to surrounding text or control height.