Skip to content
Kimenpre-v1documentation home
Color scheme

ki-icon

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();
Confirmed
<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

AttributePropertyTypeDefaultDescription
labellabelstring | undefined–Accessible name for a meaningful glyph. Omit it when nearby text already conveys the meaning.
namenamestring–Lucide name made available by a per-icon import. An unavailable name draws no glyph.
sizesize"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.

TokenDescription
--ki-icon-size-lgLarge ki-icon with the surrounding text ink.
--ki-icon-size-mdMedium ki-icon with the surrounding text ink.
--ki-icon-size-smSmall ki-icon with the surrounding text ink.
--ki-icon-stroke-widthLucide stroke width in viewBox units, scaled with the glyph.
--ki-typography-family-bodysemantic font family for typography family body.

Open ki-icon in Storybook