ki-icon
@kimen/elements/ki-icon- Source
- Agent reference
Import each glyph your application uses before the page mounts. The public
subpaths support Lucide’s names and aliases. Use the same spelling in the
import and in the name attribute.
import '@kimen/elements/icons/circle-check';import '@kimen/elements/icons/triangle-alert';import { defineCustomElement } from '@kimen/elements/ki-icon';
defineCustomElement();<span><ki-icon name="circle-check"></ki-icon> Confirmed</span><ki-icon name="triangle-alert" label="Warning" size="lg"></ki-icon>Leave off label when the adjacent text already conveys the meaning. Supply
a localized label when the glyph stands on its own. For an icon-only button,
put the label on the button and leave the slotted icon decorative.
The SVG follows the surrounding text ink and defaults to 1em. Use
sm, md or lg for the theme’s 16, 20 or 24px size, respectively, at a
16px root. Meaningful icons need at least 3:1 contrast on their background.
Use a semantic high-emphasis text ink on the page surface. Check the contrast
if you choose a medium-emphasis ink or a different background.
Guarded applications import the glyph names they allow. A name with no import produces a catalog diagnostic. Standalone icons with unavailable names render empty.
API reference
When to use: show a named glyph next to text, or give a standalone meaningful glyph an accessible label. Import @kimen/elements/icons/<name> before mounting the component or rendering a guarded surface.
When not to use: make an icon interactive, accept arbitrary SVG or URLs, or replace the accessible name of a control. Use the control's own label.
Properties & attributes
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
label | label | string | undefined | – | Accessible name for a meaningful glyph. Omit it when nearby text already conveys the meaning. |
name | name | string | – | Lucide name made available by a per-icon import. An unavailable name draws no glyph. |
size | size | "inherit" | "lg" | "md" | "sm" | 'inherit' | Glyph size. Inherit follows the surrounding text at 1em. |
CSS custom properties
The public styling contract of ki-icon: reassign these tokens at :root or on a subtree — never override internals.
| Token | Description |
|---|---|
--ki-icon-size-lg | Large ki-icon with the surrounding text ink. |
--ki-icon-size-md | Medium ki-icon with the surrounding text ink. |
--ki-icon-size-sm | Small ki-icon with the surrounding text ink. |
--ki-icon-stroke-width | Lucide stroke width in viewBox units, scaled with the glyph. |
--ki-typography-family-body | semantic font family for typography family body. |