Skip to content
Kimenpre-v1documentation home
Color scheme

ki-combobox

Use Combobox when people need to find a choice in a long list, select several values, or add a new value to the list.

Theme for this example
Color scheme for this example
Ana Ruiz Anabel Soto Juan Antón
<ki-combobox label="Assignee" placeholder="Search people">
<ki-option value="ana" description="[email protected]">Ana Ruiz</ki-option>
<ki-option value="anabel" description="[email protected]">Anabel Soto</ki-option>
<ki-option value="juan" description="[email protected]">Juan Antón</ki-option>
</ki-combobox>

Multiple choices

Set multiple to show selected values as removable tags. Add allow-custom to let someone choose text they typed. Use a JavaScript array to assign value or encode the array as a JSON string in HTML. Forms submit multiple values as repeated entries under the same name.

Theme for this example
Color scheme for this example
bug search documentation
<ki-combobox label="Labels" placeholder="Add a label" multiple allow-custom value='["bug","search"]'>
<ki-option>bug</ki-option>
<ki-option>search</ki-option>
<ki-option>documentation</ki-option>
</ki-combobox>

Remote results

Set filter="none". Listen for ki-input and use event.detail.value to fetch results. Set loading until the latest results have replaced the option children. Listen for change to read the committed value.

Accessibility

Give the field a visible label. An option can add secondary text with description and decorative content with the start slot. Use Up and Down to navigate, Enter to choose, Escape to close and then clear, and Backspace to remove the last tag when the query is empty. The text field announces the result count and each tag has a named removal button.

API reference

When to use: choose from a long list of options, let people search an option source, or allow multiple selections that remain visible as tags.

When not to use: use a select-only control for a short closed set or a plain text field for unrestricted input with no choices.

Properties & attributes

AttributePropertyTypeDefaultDescription
add-labeladdLabelstring'Add “{text}”'Localizable free-entry offer. {text} is replaced by the trimmed query.
allow-customallowCustombooleanfalseOffers to add trimmed query text when no known or selected choice already matches it.
disableddisabledbooleanfalseDisables editing, navigation and form submission.
empty-labelemptyLabelstring'No results'Localizable status when there are no choices to display.
error-texterrorTextstring | undefined–Message used when a required selection is missing, in place of the browser's message.
filterfilter"contains" | "none" | "starts-with"'contains'Filters by label. Set to none when the application provides results from a remote search.
help-texthelpTextstring | undefined–Guidance shown below the field and read as its description.
labellabelstring–Visible label and accessible name. Supply it even when placeholder text is also set.
loadingloadingbooleanfalseReplaces visible options with a loading indicator while a search is pending.
loading-labelloadingLabelstring'Loading results'Localizable status while waiting for a result set.
multiplemultiplebooleanfalseEnables ordered multiple selection and renders selected values as tags.
namenamestring | undefined–Form-data key. Multiple choices contribute one entry each under this name.
placeholderplaceholderstring''Hint shown in the text input when it is empty.
remove-labelremoveLabelstring'Remove {label}'Localizable removal button label. {label} is replaced by the selected label.
requiredrequiredbooleanfalseRequires a committed choice to submit the form.
result-count-labelresultCountLabelstring'{count} results'Localizable status for several choices. {count} is replaced by the result count.
result-one-labelresultOneLabelstring'1 result'Localizable status for one available choice.
valuevaluestring | string[]''Committed value. Use a string for single selection and an array of strings for multiple selection. In HTML and catalog specs, encode multiple values as a JSON array string in the value attribute, or supply one literal value. Assign a new array to change multiple selections programmatically.

Events

EventDetail typeDescription
ki-inputCustomEvent<{ value: string }>Reports a raw text edit in detail.value. Listen to it to request remote results.
changeEventComposed event after a user changes the committed selection. Read the committed value from the host.

Slots

SlotDescription
(default)Declarative ki-option children. Supply unique values and a human-readable label.

CSS parts

PartDescription
descriptionAn option's secondary text.
errorPolite error message shown after failed validation.
fieldContainer for the text input and selected tags.
helpHelp below the field.
inputNative text input with the combobox role.
labelVisible label of the field and its listbox.
listboxFloating listbox surface.
optionA mirrored choice row.
removeA native button that removes a selected tag.
tagA selected value in multiple mode.

CSS custom properties

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

TokenDescription
--ki-combobox-field-bgFill for the editable field.
--ki-combobox-field-borderOutline around the editable field.
--ki-combobox-field-fgText on the editable field.
--ki-combobox-field-heightResting minimum block size of the field.
--ki-combobox-icon-sizeSize of search, selection and remove glyphs.
--ki-combobox-input-basisPreferred text-entry width before a row of tags wraps.
--ki-combobox-input-touch-font-sizeMinimum editable text size for coarse-pointer input.
--ki-combobox-listbox-backdrop-filterComplete backdrop filter for the floating listbox.
--ki-combobox-listbox-bgFill for the floating listbox.
--ki-combobox-listbox-bg-imageOptional image layered over the floating listbox.
--ki-combobox-listbox-borderOutline around the floating listbox.
--ki-combobox-listbox-fgText on the floating listbox.
--ki-combobox-listbox-max-block-sizeMaximum listbox block size before options scroll.
--ki-combobox-listbox-shadowElevation of the floating listbox.
--ki-combobox-match-fgForeground of the first bolded query match.
--ki-combobox-option-active-bgFill for the active option.
--ki-combobox-option-active-fgText on the active option.
--ki-combobox-tag-bgFill for the selected tag.
--ki-combobox-tag-fgText on the selected tag.
--ki-corner-field-itemCorner radius for choices and tokens inside an editable field.
--ki-corner-field-surfaceCorner radius for an editable field and its floating choice surface.
--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-offsetGap between a focusable component and its keyboard focus ring.
--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-layout-spacing-mdThe md spacing step for a stack or grid gap.
--ki-layout-spacing-xsThe xs spacing step for a stack or grid gap.
--ki-layout-spacing-xxsThe xxs spacing step for a stack or grid gap.
--ki-outline-danger-high-emsemantic color for outline danger high em.
--ki-outline-hairline-widthWidth of a hairline component surface edge.
--ki-text-danger-high-emsemantic color for text danger high em.
--ki-text-high-emsemantic color for text 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-1semantic dimension for typography line height body 1.
--ki-typography-line-height-caption-2semantic dimension for typography line height caption 2.
--ki-typography-size-body-1semantic dimension for typography size body 1.
--ki-typography-size-caption-2semantic dimension for typography size caption 2.
--ki-typography-visually-hidden-sizeNonzero edge for clipped text available to assistive technology.
--ki-typography-weight-body-boldsemantic font weight for typography weight body bold.
--ki-typography-weight-body-mediumsemantic font weight for typography weight body medium.

Workshop

Open ki-combobox in Storybook