Skip to content
Kimenpre-v1documentation home
Color scheme

ki-empty-state

Use EmptyState when a view has no items. Name what is empty and give a next step. Supply a primary action when the user can do something about it. Use ki-spinner while results are loading.

First run

Choose a heading level that fits the surrounding page. The default is level three. Import the Lucide glyph by name before mounting an icon example.

import '@kimen/elements/icons/folder-plus';
<ki-empty-state heading="No projects yet" icon-name="folder-plus" tone="primary-light">
Projects hold your surfaces, catalogs and themes.
<ki-button slot="actions" variant="primary">New project</ki-button>
</ki-empty-state>

Slot an illustration into media to replace the icon. Use decorative media with empty alternative text and keep interactive controls in actions.

Search results

Use size="sm" in a table or panel. Set announce before inserting the component to put the message in a polite status region. The action controls stay outside that region and retain their usual keyboard behavior.

Theme for this example
Color scheme for this example
Check the spelling or remove a filter. Clear filters
<ki-empty-state heading="No results for webhok" heading-level="2" size="sm" announce>
Check the spelling or remove a filter.
<ki-button slot="actions" variant="secondary">Clear filters</ki-button>
</ki-empty-state>

API reference

When to use: explain an empty list, table, search result, or first-run view. Supply a localized heading that names what is empty and a short next step. Use announce for results that change after an interaction.

When not to use: signal that results are loading or draw attention to an error that needs acknowledgement. Use ki-spinner or ki-alert for those states.

Properties & attributes

AttributePropertyTypeDefaultDescription
announceannouncebooleanfalsePut the heading and description in a polite status, with actions outside the region. Set before mounting a message that reports changed results.
headingheadingstring–Localized heading that identifies the empty view. Blank text omits the heading.
heading-levelheadingLevelnumber3Native heading level for the surrounding document outline. Only integers from 2 through 6 are valid; unsupported values use level 3.
icon-nameiconNamestring | undefined–Optional decorative Lucide glyph. Register it with a per-icon import before mounting. A supplied illustration takes precedence.
sizesize"md" | "sm"'md'Use small inside a table or narrow panel. Unrecognized sizes use the medium layout.
tonetone"danger" | "info" | "neutral" | "primary" | "primary-light" | "success" | "warning"'neutral'FeatureIcon tone. Unrecognized tones use the neutral tile.

Slots

SlotDescription
(default)Localized supporting text with a reason or recovery advice.
actionsOptional controls for the next step, with at most one primary action. In a guarded surface, bind actions to these controls.
mediaOptional decorative illustration in place of the icon. Use an image with empty alt text or a decorative SVG. Keep this slot free of controls.

CSS parts

PartDescription
actionsWrapping row of consumer-supplied controls.
containerCentered layout for the illustration, message and actions.
descriptionWrapper for the default slot.
headingNative heading at the selected document level.
mediaDecorative illustration or FeatureIcon tile.

CSS custom properties

The public styling contract of ki-empty-state: reassign these tokens at :root or on a subtree — never override internals.

TokenDescription
--ki-empty-state-backdrop-filterComplete filter applied behind the empty view.
--ki-empty-state-bgBackground behind the empty view.
--ki-empty-state-bg-imageOptional image above the background color.
--ki-empty-state-description-bgBackground layer behind the supporting copy.
--ki-empty-state-description-fgSupporting text ink, strengthened in contrast-more mode.
--ki-empty-state-description-line-heightLine height of the supporting copy.
--ki-empty-state-description-sizeFont size of the supporting copy.
--ki-empty-state-fgForeground ink for the heading.
--ki-empty-state-gapGap between the decorative media, message and action row.
--ki-empty-state-gap-smGap between regions in a compact empty view.
--ki-empty-state-heading-font-familyTypeface for the native heading.
--ki-empty-state-heading-line-heightHeading line height in a regular empty view.
--ki-empty-state-heading-line-height-smHeading line height in a compact empty view.
--ki-empty-state-heading-sizeHeading font size in a regular empty view.
--ki-empty-state-heading-size-smHeading font size in a compact empty view.
--ki-empty-state-heading-weightWeight of the heading.
--ki-empty-state-max-widthMaximum inline size of the centered content.
--ki-empty-state-tile-danger-bgBackground of the danger decorative tile.
--ki-empty-state-tile-danger-fgGlyph ink on the danger decorative tile.
--ki-empty-state-tile-info-bgBackground of the info decorative tile.
--ki-empty-state-tile-info-fgGlyph ink on the info decorative tile.
--ki-empty-state-tile-neutral-bgBackground of the neutral decorative tile.
--ki-empty-state-tile-neutral-fgGlyph ink on the neutral decorative tile.
--ki-empty-state-tile-primary-bgBackground of the primary decorative tile.
--ki-empty-state-tile-primary-fgGlyph ink on the primary decorative tile.
--ki-empty-state-tile-primary-light-bgBackground of the primary-light decorative tile.
--ki-empty-state-tile-primary-light-fgGlyph ink on the primary-light decorative tile.
--ki-empty-state-tile-radiusCorner radius of the regular fallback tile.
--ki-empty-state-tile-radius-smCorner radius of the compact fallback tile.
--ki-empty-state-tile-sizeRegular FeatureIcon fallback tile size.
--ki-empty-state-tile-size-smCompact FeatureIcon fallback tile size.
--ki-empty-state-tile-success-bgBackground of the success decorative tile.
--ki-empty-state-tile-success-fgGlyph ink on the success decorative tile.
--ki-empty-state-tile-warning-bgBackground of the warning decorative tile.
--ki-empty-state-tile-warning-fgGlyph ink on the warning decorative tile.
--ki-typography-family-bodysemantic font family for typography family body.

Workshop

Open ki-empty-state in Storybook