ki-select
@kimen/elements/ki-select- Source
- Agent reference
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.
<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>Examples
Section titled “Examples”Required, in a form
Section titled “Required, in a form”required blocks submission while empty; the selected option’s value is
submitted under name:
<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.
API reference
Section titled “API reference”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
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
disabled | disabled | boolean | false | Prevents opening, removes the trigger from keyboard reach, and excludes the select from form submission. Boolean presence semantics apply. |
error-text | errorText | string | 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-text | helpText | string | 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. |
label | label | string | – | Visible label and accessible-name source for the combobox trigger. When NOT to use: do not omit it; unlabeled selects are invalid usage. |
label-hint | labelHint | string | 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. |
name | name | string | 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. |
placeholder | placeholder | string | '' | Text shown while no option is selected. When NOT to use: do not use it as a replacement for label. |
required | required | boolean | false | Requires a non-empty submitted value. The platform validation message is donated by a hidden native select. |
size | size | "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. |
value | value | string | '' | 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
| Event | Detail type | Description |
|---|---|---|
change | Event | Fired 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
| Slot | Description |
|---|---|
| (default) | ki-option data children. They do not paint; rows are mirrored. |
CSS parts
| Part | Description |
|---|---|
error | Error 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. |
help | Help line under the trigger, read as the combobox description. |
indicator | Decorative dropdown indicator. |
label | Visible label and accessible-name source. |
label-hint | The 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. |
listbox | Popup listbox surface. |
option | Mirrored option row rendered in this shadow root. |
trigger | Native button carrying the combobox role. |
value | Displayed 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.
| Token | Description |
|---|---|
--ki-density-control-offset | Added 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-scale | Multiplies every scaled container padding and gap (card, dialog, alert, list, list item, select listbox, tab panel, tooltip). |
--ki-density-target-min | The 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-filter | Complete backdrop filter for glass components. Use none to turn the effect off. |
--ki-effect-component-secondary-default-shadow | MarsUI 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-e1 | MarsUI Elevation/e1. Scheme-aware: every layer colors through ki.elevation.shadow. |
--ki-focus-danger | MarsUI 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-sm | Motion travel distance sm (4px): small slide/settle offsets. |
--ki-motion-distance-xs | Motion travel distance xs (2px): hover-lift offsets. |
--ki-motion-duration-fast | Fast interaction transition duration. |
--ki-motion-easing-out | Decelerating interaction transition easing curve. |
--ki-motion-easing-standard | Standard interaction transition easing curve. |
--ki-option-disabled-bg | color used by the option component for disabled background. |
--ki-option-disabled-fg | color used by the option component for disabled foreground. |
--ki-option-font-size | dimension used by the option component for font size. |
--ki-option-highlight-bg | color 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-fg | color used by the option component for highlight foreground. |
--ki-option-hover-bg | color 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-fg | color used by the option component for hover foreground. |
--ki-option-min-target | dimension used by the option component for min target (MarsUI Dropmenu row height Space/11xl 36px; comfortably above the 24px a11y floor). |
--ki-option-padding-inline | dimension used by the option component for padding inline. |
--ki-option-radius | dimension used by the option component for radius (MarsUI Radius/component/radius_lg 12px bound on Dropmenu rows). |
--ki-option-rest-bg | color used by the option component for rest background (MarsUI Dropmenu rows are transparent over the glass panel; only hover/selected paint). |
--ki-option-rest-fg | color used by the option component for rest foreground. |
--ki-option-selected-bg | color used by the option component for selected background. |
--ki-option-selected-fg | color used by the option component for selected foreground. |
--ki-select-border-block-end-width | dimension used by the select component for border block end width. |
--ki-select-border-block-start-width | dimension used by the select component for border block start width. |
--ki-select-border-inline-end-width | dimension used by the select component for border inline end width. |
--ki-select-border-inline-start-width | dimension used by the select component for border inline start width. |
--ki-select-border-width | dimension 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-bg | color used by the select component for disabled background. |
--ki-select-disabled-border | color used by the select component for disabled border (MarsUI Outline/base_em Black/3). |
--ki-select-disabled-fg | color 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-fg | color used by the select component for disabled label foreground. |
--ki-select-focus-bg | color used by the select component for focus background (MarsUI Dropdown focus fill Surface/Special/light-s0_dark-s4). |
--ki-select-focus-border | color 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-fg | color used by the select component for focus foreground. |
--ki-select-focus-label-fg | color used by the select component for focus label foreground. |
--ki-select-focus-ring-color | color used by the select component for focus ring color. |
--ki-select-focus-ring-offset | dimension used by the select component for focus ring offset. |
--ki-select-focus-ring-shadow | shadow 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-width | dimension used by the select component for focus ring width. |
--ki-select-font-size | dimension used by the select component for font size. |
--ki-select-font-weight | font weight used by the select component for the trigger value (MarsUI UI/Body 1/medium: weight 600). |
--ki-select-gap | dimension used by the select component for gap. |
--ki-select-height | dimension used by the select component for height. |
--ki-select-hover-border | color 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-fg | color used by the select component for hover foreground. |
--ki-select-hover-label-fg | color used by the select component for hover label foreground. |
--ki-select-indicator-glyph-size | dimension 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-size | dimension used by the select component for indicator size. |
--ki-select-label-font-size | dimension used by the select component for label font size (MarsUI UI/Para/medium: body_1 13px). |
--ki-select-label-font-weight | font weight used by the select component for label font weight. |
--ki-select-label-gap | dimension used by the select component for label gap. |
--ki-select-label-hint-fg | color 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-gap | dimension 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-height | dimension used by the select component for label line height (MarsUI line_height/para 20px). |
--ki-select-label-padding-inline | dimension 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-size | dimension used by the select component for lg font size: body-2 (Input-cell 8016:286 lg, composed by Dropdown 12041:1595). |
--ki-select-lg-height | dimension used by the select component for lg height (Input-cell 8016:286 lg, composed by Dropdown 12041:1595: 48px). |
--ki-select-lg-indicator-size | dimension 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-size | dimension 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-height | dimension used by the select component for the lg label line height (body-2, Input-label lg; spec 050 D4). |
--ki-select-lg-line-height | dimension 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-inline | dimension 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-radius | dimension 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-height | dimension used by the select component for the trigger value line height (MarsUI body_1 24px). |
--ki-select-listbox-backdrop-filter | Complete backdrop filter behind the select listbox. |
--ki-select-listbox-bg | color 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-image | Optional CSS background image layered over the listbox fill. Use none for a solid fill. |
--ki-select-listbox-max-block-size | dimension 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-offset | dimension used by the select component for listbox offset. |
--ki-select-listbox-padding | dimension used by the select component for listbox padding (Dropmenu master Body: Space/md 8px on every side). |
--ki-select-listbox-radius | dimension used by the select component for listbox radius (Dropmenu master 12127:30113: Radius/big-component/xs 16px). |
--ki-select-listbox-shadow | shadow 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-target | dimension used by the select component for min target. |
--ki-select-padding-inline | dimension used by the select component for padding inline. |
--ki-select-placeholder-fg | color used by the select component for placeholder foreground. |
--ki-select-radius | dimension used by the select component for radius (MarsUI Radius/component/radius_md 10px; component ramp so personality modes reach it). |
--ki-select-rest-bg | color 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-border | color used by the select component for rest border. |
--ki-select-rest-fg | color used by the select component for rest foreground. |
--ki-select-rest-label-fg | color used by the select component for rest label foreground. |
--ki-select-sm-font-size | dimension used by the select component for sm font size: caption-2 (Input-cell 8016:286 sm, composed by Dropdown 12041:1595). |
--ki-select-sm-height | dimension used by the select component for sm height (Input-cell 8016:286 sm, composed by Dropdown 12041:1595: 32px). |
--ki-select-sm-indicator-size | dimension 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-size | dimension 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-height | dimension used by the select component for the sm label line height (caption-2, Input-label sm; spec 050 D4). |
--ki-select-sm-line-height | dimension 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-inline | dimension 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-radius | dimension 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-size | dimension used by the select component for xl font size: title-2 (Input-cell 8016:286 xl, composed by Dropdown 12041:1595). |
--ki-select-xl-height | dimension used by the select component for xl height (Input-cell 8016:286 xl, composed by Dropdown 12041:1595: 56px). |
--ki-select-xl-indicator-size | dimension 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-size | dimension 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-height | dimension used by the select component for the xl label line height (body-2, Input-label lg; spec 050 D4). |
--ki-select-xl-line-height | dimension 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-inline | dimension 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-radius | dimension 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-size | dimension 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-height | dimension used by the select component for xs height (Input-cell 8016:286 xs, composed by Dropdown 12041:1595: 24px). |
--ki-select-xs-indicator-size | dimension 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-size | dimension 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-height | dimension used by the select component for the xs label line height (caption-2, Input-label sm; spec 050 D4). |
--ki-select-xs-line-height | dimension 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-inline | dimension 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-radius | dimension 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-inverse | semantic color for surface hover overlay inverse. |
--ki-text-danger-high-em | semantic color for text danger high em. |
--ki-text-supporting | Supporting 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-body | semantic font family for typography family body. |
--ki-typography-line-height-body-2 | semantic dimension for typography line height body 2. |
--ki-typography-line-height-caption-2 | semantic dimension for typography line height caption 2. |
--ki-typography-line-height-para | semantic dimension for typography line height para. |
--ki-typography-size-body-2 | semantic dimension for typography size body 2. |
--ki-typography-size-caption-2 | semantic dimension for typography size caption 2. |
--ki-typography-weight-body-medium | semantic font weight for typography weight body medium. |
--ki-typography-weight-body-normal | semantic font weight for typography weight body normal. |
Accessibility
Section titled “Accessibility”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.