ComponentsEnterpriseCombobox

Combobox

Combobox combines text search and governed option selection in one accessible enterprise field.

ARIA comboboxSingle + multipleAsync statesCustom filtering3 sizes

Overview

Use Combobox when people need to search a governed option set faster than they can scan it, while retaining a valid selection.

Choose a project owner

Live preview

Open the popup, search by name or role, and select a person.

Search by person, role, or project.
OwnerCombobox.tsx
tsx
import { Combobox, type ComboboxOption } from 'omverse-ui'
 
const people: ComboboxOption[] = [
{ value: 'maya', label: 'Maya Chen', description: 'Program manager', icon: 'users' },
{ value: 'noah', label: 'Noah Williams', description: 'Platform engineer', icon: 'users' },
]
 
<Combobox
label="Project owner"
options={people}
value={owner}
onValueChange={setOwner}
helperText="Search by person, role, or project."
/>

Anatomy

Combobox connects a visible label, editable field, selected values, popup disclosure, and governed listbox.

⌕Maya Chen⌄

Maya Chen✓

Noah Williams

12345
  1. 1
    Label

    Names the field and communicates required context.

  2. 2
    Search input

    Filters options while keeping keyboard focus in the field.

  3. 3
    Selected value

    Displays the governed value or removable multi-select chips.

  4. 4
    Disclosure

    Opens or closes the available option list.

  5. 5
    Listbox

    Shows matching options, descriptions, and selected state.

When to use

Use Combobox for searchable governed choices, especially when the list is long, dynamic, or unfamiliar.

Recommended

  • Search large option sets

    Use for people, accounts, assets, locations, or governed codes.

  • Show distinguishing metadata

    Add descriptions when labels alone are ambiguous.

  • Support multi-selection

    Use chips when several values from the same governed set may be chosen.

When not to use

Prefer simpler fields when search or governed selection is unnecessary.

Avoid

  • Do not use for short lists

    Use Select or Radio when all options are easy to scan.

  • Do not use for unrestricted text

    Use Input when any value is valid.

  • Do not hide essential commands

    Use CommandBar or search when results are actions rather than values.

Variants

Surface and density options align Combobox with forms, filter bars, and compact enterprise workspaces.

Outlined

Provides the clearest field boundary on open surfaces.

Filled

Uses a tonal surface in dense forms and filter areas.

Multiple

Represents selected values as individually removable chips.

Sizes

Small, medium, and large preserve readable text and usable targets.

States

Combobox coordinates field, popup, option, validation, and asynchronous states without moving focus away from the input.

StateTriggerVisual responseInteraction
ClosedField is inactiveSelected value or placeholderFocus or disclosure opens
OpenField is focused or disclosedFiltered listbox appearsInput retains focus
Active optionKeyboard navigationTonal option highlightEnter selects
SelectedValue is chosenLabel or chips and option checkClear or remove updates value
LoadingOptions are being retrievedProgress and loading statusCurrent value remains visible
EmptyNo option matchesNo-results messageQuery remains editable
ErrorSelection is invalidError outline and linked messageField remains operable
DisabledField is unavailableReduced emphasisCannot open or edit

Behavior

Combobox separates text query, popup visibility, and selection so each can be controlled independently for local or remote data.

Filtering

Default matching uses label, description, and hidden keywords; applications can override it.

Active descendant

Keyboard focus stays on the input while the active option is announced.

Multiple values

Selection stays open and the query clears after each chosen value.

Remote options

Controlled query and loading props support debounced server search.

Accessibility

Combobox follows the WAI-ARIA editable combobox pattern with named input, controlled listbox, active descendant, and announced option state.

KeyAction
TabMoves focus into or out of the field.
↑↓Opens the popup and moves the active option.
HomeEndMoves to the first or last matching option.
EnterSelects the active enabled option.
EscCloses the popup without clearing selection.
  • Provide a persistent visible label.
  • Connect the combobox to its listbox with aria-controls.
  • Expose popup visibility and active option state.
  • Announce selected and disabled options.
  • Link helper or error text with aria-describedby.
  • Keep keyboard focus in the input while navigating results.

Content guidelines

Labels, placeholders, option text, and feedback should make the governed choice easy to understand before searching.

Name the value

Use a concise noun phrase for the field.

ExampleProject owner

Prompt the action

Use placeholder text that describes the searchable set.

ExampleSearch people…

Distinguish options

Use short metadata when names can repeat.

ExamplePlatform engineer

State empty results

Name the searched object in the message.

ExampleNo people found

Examples

Multiple selection uses the same option model and keyboard behavior while representing chosen values as chips.

Searchable owner field

Live preview

The live preview demonstrates controlled popup, query, and selection state.

Search by person, role, or project.
ReviewerCombobox.tsx
tsx
<Combobox
label="Reviewers"
options={people}
multiple
value={reviewers}
onValueChange={setReviewers}
variant="filled"
/>

Props / API

Combobox extends div attributes; ComboboxOption defines value, label, optional description, icon, keywords, and disabled state.

Props

PropTypeDefaultDescription
labelstringrequiredVisible and accessible field label.
optionsreadonly ComboboxOption[]requiredGoverned options available for selection.
multiplebooleanfalseEnables multiple selection with removable chips.
valuestring | readonly string[]undefinedControlled selected value or values.
defaultValuestring | readonly string[]undefinedInitial uncontrolled selection.
onValueChange(value) => voidundefinedRuns whenever selection changes.
inputValuestringundefinedControlled text query.
defaultInputValuestring''Initial uncontrolled text query.
onInputValueChange(value: string) => voidundefinedRuns whenever the query changes.
openbooleanundefinedControlled popup visibility.
defaultOpenbooleanfalseInitial uncontrolled popup visibility.
onOpenChange(open: boolean) => voidundefinedRuns when popup visibility changes.
placeholderstring'Search options…'Prompt shown when the query is empty.
helperTextReactNodeundefinedSupporting guidance linked to the field.
errorReactNodeundefinedValidation message linked to the field.
loadingbooleanfalseShows asynchronous option progress.
disabledbooleanfalseDisables the field and popup.
requiredbooleanfalseMarks the selection required.
clearablebooleantrueAllows the current selection to be cleared.
emptyMessageReactNode'No options found.'Content shown when no option matches.
filterOption(option, query) => booleanbuilt-in text matchCustom option filtering logic.
variant'outlined' | 'filled''outlined'Sets the field surface.
size'sm' | 'md' | 'lg''md'Controls field height and type scale.