Skip to content
Kimenpre-v1documentation home
Color scheme

ki-select

A form-associated select-only combobox for choosing exactly one value from a known closed list of ki-option children — especially with roughly five or more choices or limited space.

Theme for this example
Color scheme for this example
Spain France Portugal
<ki-select label="Country" name="country" placeholder="Choose a country">
<ki-option value="es">Spain</ki-option>
<ki-option value="fr">France</ki-option>
<ki-option value="pt">Portugal</ki-option>
</ki-select>

required blocks submission while empty; the selected option’s value is submitted under name:

Theme for this example
Color scheme for this example
1-10 11-50 51+ Continue
<form onsubmit="event.preventDefault()">
<ki-select label="Team size" name="size" required>
<ki-option>1-10</ki-option>
<ki-option>11-50</ki-option>
<ki-option disabled>51+</ki-option>
</ki-select>
<ki-button variant="primary">Continue</ki-button>
</form>

An option without value submits its trimmed label text.

When to use: choose exactly one value from a known closed list, especially when there are roughly five or more choices or space is limited.

When not to use: ki-radio-group for a few always-visible choices, ki-input for free or searchable text, ki-checkbox/ki-switch for binary decisions, or multiselect and command menus.

Properties & attributes

AttributePropertyTypeDefaultDescription
disableddisabledbooleanfalsePrevents opening, removes the trigger from keyboard reach, and excludes the select from form submission. Boolean presence semantics apply.
error-texterrorTextstring | undefined–Message shown in place of the help text once a required select is left without a choice, and its validationMessage ("Choose a country"). Without it the browser's own message shows, in the browser's language. An error set with setCustomValidity outranks it. When NOT to use: do not use it for server-side or cross-field errors; call setCustomValidity for those.
help-texthelpTextstring | undefined–One line of help under the trigger, read with it as the combobox description: what the choice decides. While an error shows, the error takes its place. When NOT to use: do not repeat the label, and do not use it for error messages; use error-text.
labellabelstring–Visible label and accessible-name source for the combobox trigger. When NOT to use: do not omit it; unlabeled selects are invalid usage.
label-hintlabelHintstring | undefined–Short text shown after the label and read with it as part of the combobox name, so people know before submitting whether to choose: "(optional)" on the few optional fields of a mostly required form, or "(required)" the other way round, in the page's own language. It changes no validation; set required for that, and keep the two consistent. When NOT to use: do not put instructions in it (use help-text), errors (use error-text), or a repeat of the label.
namenamestring | undefined–Form-data key used when a selected option contributes its value. When NOT to use: omit it when the select should not submit data.
placeholderplaceholderstring''Text shown while no option is selected. When NOT to use: do not use it as a replacement for label.
requiredrequiredbooleanfalseRequires a non-empty submitted value. The platform validation message is donated by a hidden native select.
sizesize"lg" | "md" | "sm" | "xl" | "xs"'md'Token-backed trigger size (--ki-select-{size}-* tokens): the trigger is 24, 32, 40, 48 or 56px tall in onmars, with its padding, radius, text and indicator; the label and help text follow in three steps. The listbox and its options keep their size. An unrecognized value matches no style rule and keeps the medium metrics. When to use: match the size of the fields around it. 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''Live projection of the selected option value, or "" when unselected. Assigning it selects the first matching option silently; the attribute is the reset/default declaration and is not updated by user commits.

Events

EventDetail typeDescription
changeEventFired once after the user commits a different option, composed across the shadow boundary and preceded by input; value is already current when listeners run. When to use: react to the committed choice. When NOT to use: do not expect it for programmatic value writes, which are silent.

Slots

SlotDescription
(default)ki-option data children. They do not paint; rows are mirrored.

CSS parts

PartDescription
errorError line shown in place of the help text while the select is invalid after the person chose or submitted; a polite live region, starting with a decorative error symbol.
helpHelp line under the trigger, read as the combobox description.
indicatorDecorative dropdown indicator.
labelVisible label and accessible-name source.
label-hintThe label-hint text after the label text, inside the label and part of the accessible name of the combobox and its listbox; rendered only while a hint is set.
listboxPopup listbox surface.
optionMirrored option row rendered in this shadow root.
triggerNative button carrying the combobox role.
valueDisplayed selection or placeholder.

CSS custom properties

The public styling contract of ki-select: 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-effect-component-backdrop-filterComplete backdrop filter for glass components. Use none to turn the effect off.
--ki-effect-component-secondary-default-shadowMarsUI Component_effect/secondary_default: drop 0/2/1.5/-0.5 plus inner White/3 0/2/3. Pair with --ki-effect-component-backdrop-filter.
--ki-elevation-e1MarsUI Elevation/e1. Scheme-aware: every layer colors through ki.elevation.shadow.
--ki-focus-dangerMarsUI Focus/danger: persistent 3px spread ring of Outline/danger_base_em_alpha (danger-500 at 20% light / 40% dark) — the danger state signal on Input_field and Dropdown masters (measured rgb(252,220,219) over white). Pairs with a white fill and hairline border; Kimen keeps its opaque danger border on top as a declared a11y deviation.
--ki-motion-distance-smMotion travel distance sm (4px): small slide/settle offsets.
--ki-motion-distance-xsMotion travel distance xs (2px): hover-lift offsets.
--ki-motion-duration-fastFast interaction transition duration.
--ki-motion-easing-outDecelerating interaction transition easing curve.
--ki-motion-easing-standardStandard interaction transition easing curve.
--ki-option-disabled-bgcolor used by the option component for disabled background.
--ki-option-disabled-fgcolor used by the option component for disabled foreground.
--ki-option-font-sizedimension used by the option component for font size.
--ki-option-highlight-bgcolor used by the option component for keyboard-highlight background (MarsUI active row = same Black/3 wash plus Elevation/e1; purple is reserved for the selected tint).
--ki-option-highlight-fgcolor used by the option component for highlight foreground.
--ki-option-hover-bgcolor used by the option component for hover background (MarsUI hover_overlay_inverse Black/3 wash over the glass panel — not a solid surface step).
--ki-option-hover-fgcolor used by the option component for hover foreground.
--ki-option-min-targetdimension used by the option component for min target (MarsUI Dropmenu row height Space/11xl 36px; comfortably above the 24px a11y floor).
--ki-option-padding-inlinedimension used by the option component for padding inline.
--ki-option-radiusdimension used by the option component for radius (MarsUI Radius/component/radius_lg 12px bound on Dropmenu rows).
--ki-option-rest-bgcolor used by the option component for rest background (MarsUI Dropmenu rows are transparent over the glass panel; only hover/selected paint).
--ki-option-rest-fgcolor used by the option component for rest foreground.
--ki-option-selected-bgcolor used by the option component for selected background.
--ki-option-selected-fgcolor used by the option component for selected foreground.
--ki-select-border-block-end-widthdimension used by the select component for border block end width.
--ki-select-border-block-start-widthdimension used by the select component for border block start width.
--ki-select-border-inline-end-widthdimension used by the select component for border inline end width.
--ki-select-border-inline-start-widthdimension used by the select component for border inline start width.
--ki-select-border-widthdimension used by the select component for border width (MarsUI Input_cell strokeWeight 1px; the color stays ki.outline.control per the declared a11y deviation — only the 2px width was undocumented).
--ki-select-disabled-bgcolor used by the select component for disabled background.
--ki-select-disabled-bordercolor used by the select component for disabled border (MarsUI Outline/base_em Black/3).
--ki-select-disabled-fgcolor used by the select component for disabled foreground (MarsUI disabled text Text/base_em Gray/400; disabled cells are exempt from the contrast sweep).
--ki-select-disabled-label-fgcolor used by the select component for disabled label foreground.
--ki-select-focus-bgcolor used by the select component for focus background (MarsUI Dropdown focus fill Surface/Special/light-s0_dark-s4).
--ki-select-focus-bordercolor used by the select component for focus border (MarsUI active is glow-only: the border stays the rest hairline while Focus/primary carries the emphasis — repointed from ki.outline.primary-high-em per the fidelity audit; material3 keeps the opaque primary border via its override).
--ki-select-focus-fgcolor used by the select component for focus foreground.
--ki-select-focus-label-fgcolor used by the select component for focus label foreground.
--ki-select-focus-ring-colorcolor used by the select component for focus ring color.
--ki-select-focus-ring-offsetdimension used by the select component for focus ring offset.
--ki-select-focus-ring-shadowshadow used by the select component for the focus ring glow (MarsUI Focus/primary: 3px spread ring at 20% — see ki.focus.primary. specs/002-ki-button/design-extraction.md §2.5 recorded 40%, having read the alpha off the Dark canvas mode, same double mechanism as ki-button: glow plus the opaque indicator).
--ki-select-focus-ring-widthdimension used by the select component for focus ring width.
--ki-select-font-sizedimension used by the select component for font size.
--ki-select-font-weightfont weight used by the select component for the trigger value (MarsUI UI/Body 1/medium: weight 600).
--ki-select-gapdimension used by the select component for gap.
--ki-select-heightdimension used by the select component for height.
--ki-select-hover-bordercolor used by the select component for hover border. Brief §1: hover moves along the neutral outline em ramp (Black/12), matching ki-input/ki-textarea; the primary accent outline is the focus language (Focus/primary), not hover.
--ki-select-hover-fgcolor used by the select component for hover foreground.
--ki-select-hover-label-fgcolor used by the select component for hover label foreground.
--ki-select-indicator-glyph-sizedimension used by the select component for the chevron glyph box inside the 18px indicator slot (MarsUI Dropdown chevron 8px border-box square drawn by [part=indicator]::before).
--ki-select-indicator-sizedimension used by the select component for indicator size.
--ki-select-label-font-sizedimension used by the select component for label font size (MarsUI UI/Para/medium: body_1 13px).
--ki-select-label-font-weightfont weight used by the select component for label font weight.
--ki-select-label-gapdimension used by the select component for label gap.
--ki-select-label-hint-fgcolor used by the select component for the label hint after the label text (spec 047: the supporting-text role, a declared a11y deviation from the MarsUI Input_label support text Text/low_em, which reads 2.8-3.13:1 on the onmars light surfaces; under more contrast it strengthens with every other supporting text).
--ki-select-label-hint-gapdimension used by the select component for the gap between the label text and the label hint (MarsUI Input_label: Space/xs 4px).
--ki-select-label-line-heightdimension used by the select component for label line height (MarsUI line_height/para 20px).
--ki-select-label-padding-inlinedimension used by the select component for label padding inline (MarsUI Input_label row 2px inset aligning the label ink with the cell radius; matches ki-input/ki-textarea).
--ki-select-lg-font-sizedimension used by the select component for lg font size: body-2 (Input-cell 8016:286 lg, composed by Dropdown 12041:1595).
--ki-select-lg-heightdimension used by the select component for lg height (Input-cell 8016:286 lg, composed by Dropdown 12041:1595: 48px).
--ki-select-lg-indicator-sizedimension used by the select component for the lg indicator box (Input-cell 8016:286 lg, composed by Dropdown 12041:1595: icon 20px).
--ki-select-lg-label-font-sizedimension used by the select component for the lg label font size: the Input-label 12021:6068 lg step, body-2 (spec 050 D4).
--ki-select-lg-label-line-heightdimension used by the select component for the lg label line height (body-2, Input-label lg; spec 050 D4).
--ki-select-lg-line-heightdimension used by the select component for lg line height (body-2, Input-cell 8016:286 lg, composed by Dropdown 12041:1595).
--ki-select-lg-padding-inlinedimension used by the select component for lg padding inline (Input-cell 8016:286 lg, composed by Dropdown 12041:1595: Space/xl, 12px).
--ki-select-lg-radiusdimension used by the select component for lg radius (Input-cell 8016:286 lg, composed by Dropdown 12041:1595: Radius/small-component/lg).
--ki-select-line-heightdimension used by the select component for the trigger value line height (MarsUI body_1 24px).
--ki-select-listbox-backdrop-filterComplete backdrop filter behind the select listbox.
--ki-select-listbox-bgcolor used by the select component for listbox background (MarsUI Dropmenu glass panel Surface/Special/blur_base_light White/80; pair with --ki-select-listbox-backdrop-filter).
--ki-select-listbox-bg-imageOptional CSS background image layered over the listbox fill. Use none for a solid fill.
--ki-select-listbox-max-block-sizedimension used by the select component for listbox max block size (surface size scale; the former ki.space.25xl reference misused the spacing scale).
--ki-select-listbox-offsetdimension used by the select component for listbox offset.
--ki-select-listbox-paddingdimension used by the select component for listbox padding (Dropmenu master Body: Space/md 8px on every side).
--ki-select-listbox-radiusdimension used by the select component for listbox radius (Dropmenu master 12127:30113: Radius/big-component/xs 16px).
--ki-select-listbox-shadowshadow used by the select component for the listbox: MarsUI elevation ramp e3 (brief §5), the medium floating-surface level, replacing the former hand-composed offset/color shadow. Declared level: e3 (M3 analog: menu/dialog band; material3 overrides to e2 = md.sys.elevation.level2 for menus).
--ki-select-min-targetdimension used by the select component for min target.
--ki-select-padding-inlinedimension used by the select component for padding inline.
--ki-select-placeholder-fgcolor used by the select component for placeholder foreground.
--ki-select-radiusdimension used by the select component for radius (MarsUI Radius/component/radius_md 10px; component ramp so personality modes reach it).
--ki-select-rest-bgcolor used by the select component for rest background (MarsUI Dropdown rest fill Surface/Special/light-s0_dark-s2: white light, Dark/800 dark).
--ki-select-rest-bordercolor used by the select component for rest border.
--ki-select-rest-fgcolor used by the select component for rest foreground.
--ki-select-rest-label-fgcolor used by the select component for rest label foreground.
--ki-select-sm-font-sizedimension used by the select component for sm font size: caption-2 (Input-cell 8016:286 sm, composed by Dropdown 12041:1595).
--ki-select-sm-heightdimension used by the select component for sm height (Input-cell 8016:286 sm, composed by Dropdown 12041:1595: 32px).
--ki-select-sm-indicator-sizedimension used by the select component for the sm indicator box (Input-cell 8016:286 sm, composed by Dropdown 12041:1595: icon 16px).
--ki-select-sm-label-font-sizedimension used by the select component for the sm label font size: the Input-label 12021:6068 sm step, caption-2 (spec 050 D4).
--ki-select-sm-label-line-heightdimension used by the select component for the sm label line height (caption-2, Input-label sm; spec 050 D4).
--ki-select-sm-line-heightdimension used by the select component for sm line height (caption-2, Input-cell 8016:286 sm, composed by Dropdown 12041:1595).
--ki-select-sm-padding-inlinedimension used by the select component for sm padding inline (Input-cell 8016:286 sm, composed by Dropdown 12041:1595: Space/md, 8px).
--ki-select-sm-radiusdimension used by the select component for sm radius (Input-cell 8016:286 sm, composed by Dropdown 12041:1595: Radius/small-component/sm).
--ki-select-xl-font-sizedimension used by the select component for xl font size: title-2 (Input-cell 8016:286 xl, composed by Dropdown 12041:1595).
--ki-select-xl-heightdimension used by the select component for xl height (Input-cell 8016:286 xl, composed by Dropdown 12041:1595: 56px).
--ki-select-xl-indicator-sizedimension used by the select component for the xl indicator box (Input-cell 8016:286 xl, composed by Dropdown 12041:1595: icon 24px).
--ki-select-xl-label-font-sizedimension used by the select component for the xl label font size: the Input-label 12021:6068 lg step, body-2 (spec 050 D4).
--ki-select-xl-label-line-heightdimension used by the select component for the xl label line height (body-2, Input-label lg; spec 050 D4).
--ki-select-xl-line-heightdimension used by the select component for xl line height (title-2, Input-cell 8016:286 xl, composed by Dropdown 12041:1595).
--ki-select-xl-padding-inlinedimension used by the select component for xl padding inline (Input-cell 8016:286 xl, composed by Dropdown 12041:1595: Space/2xl, 14px).
--ki-select-xl-radiusdimension used by the select component for xl radius (Input-cell 8016:286 xl, composed by Dropdown 12041:1595: Radius/small-component/xl).
--ki-select-xs-font-sizedimension used by the select component for xs font size: caption-2 (Input-cell 8016:286 xs, composed by Dropdown 12041:1595). Figma draws caption_1, 10px; caption_2, 12px, is the smallest text the library ships (spec 050 D7).
--ki-select-xs-heightdimension used by the select component for xs height (Input-cell 8016:286 xs, composed by Dropdown 12041:1595: 24px).
--ki-select-xs-indicator-sizedimension used by the select component for the xs indicator box (Input-cell 8016:286 xs, composed by Dropdown 12041:1595: icon 14px).
--ki-select-xs-label-font-sizedimension used by the select component for the xs label font size: the Input-label 12021:6068 sm step, caption-2 (spec 050 D4).
--ki-select-xs-label-line-heightdimension used by the select component for the xs label line height (caption-2, Input-label sm; spec 050 D4).
--ki-select-xs-line-heightdimension used by the select component for xs line height (caption-2, Input-cell 8016:286 xs, composed by Dropdown 12041:1595).
--ki-select-xs-padding-inlinedimension used by the select component for xs padding inline (Input-cell 8016:286 xs, composed by Dropdown 12041:1595: Space/sm, 6px).
--ki-select-xs-radiusdimension used by the select component for xs radius (Input-cell 8016:286 xs, composed by Dropdown 12041:1595: Radius/small-component/xs).
--ki-surface-hover-overlay-inversesemantic color for surface hover overlay inverse.
--ki-text-danger-high-emsemantic color for text danger high em.
--ki-text-supportingSupporting text of an enabled control: field labels, placeholders, list secondary lines, quiet button labels and unselected tabs. A role, distinct from the med-em emphasis step it resolves to, so a mode can strengthen enabled supporting text without touching the disabled ink that also draws from med-em (directly, or through text.muted).
--ki-typography-family-bodysemantic font family for typography family body.
--ki-typography-line-height-body-2semantic dimension for typography line height body 2.
--ki-typography-line-height-caption-2semantic dimension for typography line height caption 2.
--ki-typography-line-height-parasemantic dimension for typography line height para.
--ki-typography-size-body-2semantic dimension for typography size body 2.
--ki-typography-size-caption-2semantic dimension for typography size caption 2.
--ki-typography-weight-body-mediumsemantic font weight for typography weight body medium.
--ki-typography-weight-body-normalsemantic font weight for typography weight body normal.

The label prop is mandatory — placeholder is never a label substitute. The composed change event fires at the host exactly like a native select. For a few always-visible choices use ki-radio-group; for free or searchable text use ki-input; multiselect and command menus are out of scope.

Open ki-select in Storybook