ComboBox
Text input with autocomplete suggestions, async loading support, free-form entry, and keyboard navigation.
Anatomy
- 1 Input field — editable text entry for typeahead filtering.
- 2 Controls — clear, loading, and expand/collapse affordances.
- 3 Suggestion list — filtered options, async status, or a free-form value action.
Options
| Property | Values | Default |
|---|---|---|
| options | Array of {value, label, description, keywords, disabled} | [] |
| placeholder | text | — |
| value | selected value | — |
| loading | true / false | false |
| allowCustomValue | true / false | false |
| state | default / hover / active / focus / disabled | default |
Behaviors
Typeahead filtering
Filtering happens as the user types. Matching checks labels, values, descriptions, groups, and optional keywords.
Async loading
Set the loading attribute while remote suggestions are pending, then update the options property when results arrive.
Free-form value
When allow-custom-value is present, unmatched text can be committed as a submitted value.
Custom option rendering
Use an option-template reference when labels need richer layouts such as helper text, region names, or additional metadata.
Usage guidelines
<uif-combobox aria-label="Destination">…</uif-combobox>
Do
Use ComboBox when typing is faster than scanning a long list or when suggestions come from an async source.
<select> with 50 options
Don't
Don't replace a native select unless filtering, async loading, or free-form entry is genuinely needed.
Content standards
- Placeholder text should describe the search target, not restate the field label.
- Option labels should stay short and scannable; move detail into
descriptionwhen needed. - Free-form input should be constrained by downstream validation when the field feeds structured data.
Keyboard interactions
| Key | Interaction |
|---|---|
| Tab | Moves focus into or out of the field and commits the current value if appropriate. |
| ↑ ↓ | Opens the list and moves the active option. |
| Home / End | Moves to the first or last enabled option when the list is open. |
| Enter | Selects the active option or commits the free-form value. |
| Escape | Closes the list and restores the last committed selection. |
| Type-ahead | Filters available options in place. |
Accessibility
- The input uses the ARIA
comboboxpattern with an associatedlistboxand active descendant. - Always provide a visible label or
aria-label/aria-labelledby. - Loading and empty states announce status updates with
role="status"andaria-live="polite". - Free-form values should be validated the same way as other user-entered text before submission.
Theming
ComboBox adapts automatically across brands and color modes through dedicated component tokens. Use the hero switches above to review brand/mode combinations.
Design checklist
--uif-combobox-* tokens.