Skip to content
Kimenpre-v1documentation home
Color scheme

ki-list-item

A row in ki-list with primary text and optional leading media, supporting text, and trailing content. See ki-list for selection and forms.

Theme for this example
Color scheme for this example
Quarterly report Updated 2 days ago 1.2 MB
<ki-list>
<ki-list-item>
<span slot="start" aria-hidden="true">📄</span>
Quarterly report
<span slot="secondary">Updated 2 days ago</span>
<span slot="end">1.2 MB</span>
</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>

When to use: as a direct child of ki-list, for a static entry, link, selection option, or a settings row with one control.

When not to use: as a menu item, tabular row, or row with several actions.

Properties & attributes

AttributePropertyTypeDefaultDescription
disableddisabledbooleanfalseExcludes this option from focus, selection by the user, and form data.
hrefhrefstring | undefined–Native row link destination. Use outside selection lists, with no slotted interactive content.
selectedselectedbooleanfalseWhether this row is selected in a single- or multiple-selection list.
sizesize"lg" | "md" | "sm" | "xl"'md'Token-backed row size (--ki-list-item-{size}-* tokens): minimum height (48, 56, 64 or 72px with a secondary line in onmars), padding, gap and text. Slotted start and end content keeps the size its author gave it. An unrecognized value matches no style rule and keeps the medium metrics. When to use: give every row of one list the same size. When NOT to use: do not pick a smaller size to fit a dense region or a larger one for touch; declare data-ki-density on the region instead, which composes with every size.
valuevaluestring | undefined–Submitted option value. The primary row text supplies the default.

Slots

SlotDescription
(default)Primary text line.
endTrailing media, meta text or the only control of a settings row.
secondarySupporting text below the primary line. Its presence selects the multi-line min-height token.
startLeading media such as an icon, avatar or image.

CSS parts

PartDescription
contentText column containing primary and secondary lines.
endTrailing region wrapper.
indicatorDecorative navigation or selection indicator.
itemItem row surface and layout container.
startLeading region wrapper.

CSS custom properties

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

TokenDescription
--ki-density-control-offsetAdded to the block size of every scaled control and row (button, icon button, field, select, textarea, option, list item, tab). Components floor the result at ki.size.target-min.
--ki-density-space-scaleMultiplies every scaled container padding and gap (card, dialog, alert, list, list item, select listbox, tab panel, tooltip).
--ki-density-target-minThe smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1).
--ki-focus-ring-colorColour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme.
--ki-focus-ring-widthThickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once.
--ki-inverse-white-alpha-3semantic color for inverse white alpha 3.
--ki-inverse-white-alpha-6semantic color for inverse white alpha 6.
--ki-list-item-checkbox-radiusCorner radius of a multiple-selection indicator.
--ki-list-item-checkbox-selected-bgFill of the selected multiple-choice indicator.
--ki-list-item-checkbox-selected-fgCheck mark ink on the selected indicator.
--ki-list-item-gapdimension used by the list component for item gap (MarsUI md/lg rows: Space/xl 12px between start/content/end regions).
--ki-list-item-hover-bgBackground of an unselected hovered interactive list row.
--ki-list-item-hover-fgText and indicator on an unselected hovered interactive list row.
--ki-list-item-indicator-border-widthStroke around a visual option indicator.
--ki-list-item-indicator-sizeEdge of the trailing selection or navigation mark.
--ki-list-item-interactive-backdrop-filterComplete backdrop filter for an interactive list row.
--ki-list-item-interactive-bgResting fill of an unselected interactive list row.
--ki-list-item-interactive-bg-imageOptional image layered over interactive list row fills.
--ki-list-item-interactive-radiusCorner radius of link and option rows.
--ki-list-item-lg-gapdimension used by the list component for lg item gap (List 10063:2066 lg binds Space/xl, 12px).
--ki-list-item-lg-min-heightdimension used by the list component for the lg one-line item min height (two List 10063:2066 lg block paddings plus the primary line: 48px).
--ki-list-item-lg-min-height-multilinedimension used by the list component for the lg two-line item min height (List 10063:2066 lg measures 64px).
--ki-list-item-lg-padding-blockdimension used by the list component for lg item padding block (List 10063:2066 lg binds Space/xl, 12px).
--ki-list-item-lg-padding-inlinedimension used by the list component for lg item padding inline (List 10063:2066 lg binds Space/md, 8px).
--ki-list-item-lg-primary-font-sizedimension used by the list component for lg primary font size (List 10063:2066 lg primary: UI/body-2).
--ki-list-item-lg-primary-line-heightdimension used by the list component for lg primary line height (List 10063:2066 lg).
--ki-list-item-lg-secondary-font-sizedimension used by the list component for lg secondary font size (List 10063:2066 lg description: UI/caption-2).
--ki-list-item-lg-secondary-line-heightdimension used by the list component for lg secondary line height (List 10063:2066 lg).
--ki-list-item-min-heightdimension used by the list component for item min height (MarsUI md text-only row is ~40px content-sized: 20px line + 2x10 padding).
--ki-list-item-min-height-multilinedimension used by the list component for multiline item min height (MarsUI md two-line row measures 56px).
--ki-list-item-padding-blockdimension used by the list component for item padding block (MarsUI md rows: Space/lg 10px).
--ki-list-item-padding-inlinedimension used by the list component for item padding inline.
--ki-list-item-primary-fgcolor used by the list component for item primary foreground.
--ki-list-item-primary-font-sizedimension used by the list component for item primary font size.
--ki-list-item-primary-font-weightfont weight used by the list component for item primary font weight.
--ki-list-item-primary-line-heightdimension used by the list component for primary line height (MarsUI primary is UI/Para/medium 13/20, not UI/Body 1 13/24).
--ki-list-item-radio-radiusCorner radius of a single-selection indicator.
--ki-list-item-radiusdimension used by the list component for item radius.
--ki-list-item-secondary-fgcolor used by the list component for item secondary foreground.
--ki-list-item-secondary-font-sizedimension used by the list component for secondary font size (MarsUI description line is UI/Caption 2: 12px).
--ki-list-item-secondary-font-weightfont weight used by the list component for item secondary font weight.
--ki-list-item-secondary-line-heightdimension used by the list component for secondary line height (MarsUI caption_2 16px; same value as before with the correct provenance).
--ki-list-item-selected-bgBackground of a selected list option.
--ki-list-item-selected-fgText and indicator on a selected list option.
--ki-list-item-sm-gapdimension used by the list component for sm item gap (List 10063:2066 sm binds Space/lg, 10px).
--ki-list-item-sm-min-heightdimension used by the list component for the sm one-line item min height (two List 10063:2066 sm block paddings plus the primary line: 32px).
--ki-list-item-sm-min-height-multilinedimension used by the list component for the sm two-line item min height (List 10063:2066 sm measures 48px).
--ki-list-item-sm-padding-blockdimension used by the list component for sm item padding block (List 10063:2066 sm binds Space/sm, 6px).
--ki-list-item-sm-padding-inlinedimension used by the list component for sm item padding inline (List 10063:2066 sm binds Space/md, 8px).
--ki-list-item-sm-primary-font-sizedimension used by the list component for sm primary font size (List 10063:2066 sm primary: UI/para).
--ki-list-item-sm-primary-line-heightdimension used by the list component for sm primary line height (List 10063:2066 sm).
--ki-list-item-sm-secondary-font-sizedimension used by the list component for sm secondary font size (List 10063:2066 sm description: UI/caption-2).
--ki-list-item-sm-secondary-line-heightdimension used by the list component for sm secondary line height (List 10063:2066 sm).
--ki-list-item-xl-gapdimension used by the list component for xl item gap (List 10063:2066 xl binds Space/3xl, 16px).
--ki-list-item-xl-min-heightdimension used by the list component for the xl one-line item min height (two List 10063:2066 xl block paddings plus the primary line: 52px).
--ki-list-item-xl-min-height-multilinedimension used by the list component for the xl two-line item min height (List 10063:2066 xl measures 72px).
--ki-list-item-xl-padding-blockdimension used by the list component for xl item padding block (List 10063:2066 xl binds Space/2xl, 14px).
--ki-list-item-xl-padding-inlinedimension used by the list component for xl item padding inline (List 10063:2066 xl binds Space/xl, 12px).
--ki-list-item-xl-primary-font-sizedimension used by the list component for xl primary font size (List 10063:2066 xl primary: UI/title-2).
--ki-list-item-xl-primary-line-heightdimension used by the list component for xl primary line height (List 10063:2066 xl).
--ki-list-item-xl-secondary-font-sizedimension used by the list component for xl secondary font size (List 10063:2066 xl description: UI/para).
--ki-list-item-xl-secondary-line-heightdimension used by the list component for xl secondary line height (List 10063:2066 xl).
--ki-motion-duration-fastFast interaction transition duration.
--ki-motion-easing-outDecelerating interaction transition easing curve.
--ki-typography-family-bodysemantic font family for typography family body.

Keep the primary text in the default slot. Mark decorative media as hidden from assistive technology or give decorative images empty alternative text. Use href for a native link or place the row in a selection list to create an option. To show a control, put one control in end on a default-mode row. The primary text names the control when it has no authored name.

Use --ki-list-item-hover-bg and --ki-list-item-hover-fg for hover, --ki-list-item-selected-bg and --ki-list-item-selected-fg for selection, and --ki-list-item-interactive-radius for interactive corners. ::part(indicator) exposes the decorative chevron, checkbox or radio.

Documented with its parent: open ki-list in Storybook