Skip to content
Kimenpre-v1documentation home
Color scheme

ki-list

A vertical list of static entries, links, settings controls, or selectable options. Use ki-list-item for each row.

Theme for this example
Color scheme for this example
Ada Lovelace Analyst Active Grace Hopper Rear admiral Away
<ki-list>
<ki-list-item>
<ki-avatar slot="start" initials="AL" label="Ada Lovelace"></ki-avatar>
Ada Lovelace
<span slot="secondary">Analyst</span>
<ki-badge slot="end" tone="success">Active</ki-badge>
</ki-list-item>
<ki-list-item>
<ki-avatar slot="start" initials="GH" label="Grace Hopper"></ki-avatar>
Grace Hopper
<span slot="secondary">Rear admiral</span>
<ki-badge slot="end" tone="neutral">Away</ki-badge>
</ki-list-item>
</ki-list>
<ki-list label="Settings">
<ki-list-item href="/settings/account">
Account
<span slot="secondary">Name, email, password</span>
</ki-list-item>
</ki-list>
Theme for this example
Color scheme for this example
Ana Garcia Luis Perez
<ki-list label="Reviewers" selection="multiple" name="reviewers" required>
<ki-list-item value="ana" selected>Ana Garcia</ki-list-item>
<ki-list-item value="luis">Luis Perez</ki-list-item>
</ki-list>
Theme for this example
Color scheme for this example
Email digest Every Monday
<ki-list label="Notifications">
<ki-list-item>
Email digest
<span slot="secondary">Every Monday</span>
<ki-switch slot="end" checked></ki-switch>
</ki-list-item>
</ki-list>

Give each interactive list a label. Set selection="single" for one choice or selection="multiple" for independent choices. Set selected on initial rows. The list’s ki-change event carries event.detail.value, a string or null in single mode and an array in multiple mode. Assign the JavaScript value property to update selection silently.

Set name to submit the selection. Multiple selections submit one entry per selected enabled row, in row order. Set required to require a choice. Form reset restores the initial selection.

When to use: settings, contacts, results, navigation or visible choices composed from primary text, supporting text and optional media. Name interactive lists.

When not to use: popup action menus, tabular data, or rows with several actions.

Properties & attributes

AttributePropertyTypeDefaultDescription
labellabelstring | undefined–Accessible name for a list with links, options or trailing controls.
namenamestring | undefined–Form field name. Multiple selection submits repeated entries under this name.
requiredrequiredbooleanfalseRequires at least one enabled choice in a selection list.
selectionselection"multiple" | "none" | "single"'none'Enables single or multiple selection. The default supports static, link and control rows.

Events

EventDetail typeDescription
ki-changeCustomEvent<KiListChangeDetail>Fires once per user selection change, after updating the form value.

Slots

SlotDescription
(default)Direct ki-list-item children.

CSS parts

PartDescription
listList surface that owns background, padding, gap and dividers.

CSS custom properties

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

TokenDescription
--ki-density-space-scaleMultiplies every scaled container padding and gap (card, dialog, alert, list, list item, select listbox, tab panel, tooltip).
--ki-list-bgcolor used by the list component for background.
--ki-list-gapdimension used by the list component for gap (MarsUI compositions stack rows contiguously; --ki-list-gap stays as the theme hook).
--ki-list-item-divider-colorcolor used by the list component for item divider color.
--ki-list-item-divider-widthdimension used by the list component for item divider width (no divider renders in any master variant; the color hook ki.list.item.divider-color stays so consumers can opt hairlines back in).
--ki-list-paddingdimension used by the list component for padding.
--ki-motion-distance-xsMotion travel distance xs (2px): hover-lift offsets.
--ki-motion-duration-fastFast interaction transition duration.
--ki-motion-duration-medium-1M3 md.sys.motion.duration.medium1 (250ms). onmars: MarsUI moderate step (240ms, 2x the 120ms base).
--ki-motion-easing-outDecelerating interaction transition easing curve.
--ki-typography-family-bodysemantic font family for typography family body.

Navigation rows are native links. A named selection list exposes a listbox with one tab stop. Arrow keys, Home, End and type-ahead move focus. Space or Enter toggles the focused option. A row accepts one interaction: its link, its option, or a control in the end slot. Development builds warn about conflicting interactions. The row’s primary text names an unlabeled trailing control.

Open ki-list in Storybook