ki-list
@kimen/elements/ki-list- Source
- Agent reference
A vertical list of static entries, links, settings controls, or selectable options. Use ki-list-item for each row.
<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>Interactive rows
Section titled “Interactive rows”<ki-list label="Settings"> <ki-list-item href="/settings/account"> Account <span slot="secondary">Name, email, password</span> </ki-list-item></ki-list><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><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.
API reference
Section titled “API reference”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
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
label | label | string | undefined | – | Accessible name for a list with links, options or trailing controls. |
name | name | string | undefined | – | Form field name. Multiple selection submits repeated entries under this name. |
required | required | boolean | false | Requires at least one enabled choice in a selection list. |
selection | selection | "multiple" | "none" | "single" | 'none' | Enables single or multiple selection. The default supports static, link and control rows. |
Events
| Event | Detail type | Description |
|---|---|---|
ki-change | CustomEvent<KiListChangeDetail> | Fires once per user selection change, after updating the form value. |
Slots
| Slot | Description |
|---|---|
| (default) | Direct ki-list-item children. |
CSS parts
| Part | Description |
|---|---|
list | List 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.
| Token | Description |
|---|---|
--ki-density-space-scale | Multiplies every scaled container padding and gap (card, dialog, alert, list, list item, select listbox, tab panel, tooltip). |
--ki-list-bg | color used by the list component for background. |
--ki-list-gap | dimension used by the list component for gap (MarsUI compositions stack rows contiguously; --ki-list-gap stays as the theme hook). |
--ki-list-item-divider-color | color used by the list component for item divider color. |
--ki-list-item-divider-width | dimension 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-padding | dimension used by the list component for padding. |
--ki-motion-distance-xs | Motion travel distance xs (2px): hover-lift offsets. |
--ki-motion-duration-fast | Fast interaction transition duration. |
--ki-motion-duration-medium-1 | M3 md.sys.motion.duration.medium1 (250ms). onmars: MarsUI moderate step (240ms, 2x the 120ms base). |
--ki-motion-easing-out | Decelerating interaction transition easing curve. |
--ki-typography-family-body | semantic font family for typography family body. |
Accessibility
Section titled “Accessibility”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.