Combobox Preview

A combobox lets people choose one or more options from a list or enter text in a connected input. Entering text will filter options or allow someone to submit a free form answer.

Comboboxes work well in situations where the list of options is very long. If the list is not very long or you can't accept free form answers, try a dropdown or a select. For a standardized form component including helper text and validation styles, use the combobox field component.

Loading...
Open in CodeSandbox
Combobox storybook
React guidance
Combobox pattern
WAI guidance

Properties

appearance

Controls the colors and borders of the combobox trigger.

“outline” “underline” “filled-darker” “filled-lighter”
Default:
“‘outline’”

as

“input”
Default:
none

defaultOpen

The default open state when open is uncontrolled

boolean
Default:
none

defaultSelectedOptions

For an uncontrolled component, sets the initial selection. If this is set, the defaultValue prop MUST also be set.

string[]
Default:
none

expandIcon

WithSlotShorthandValue<{ as?: "span"; } & Pick<DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "key" | keyof HTMLAttributes<...>> & { ...; } & { ...; }> | null
Default:
none

freeform

boolean
Default:
none

inlinePopup

Render the combobox’s popup inline in the DOM. This has accessibility benefits, particularly for touch screen readers.

boolean
Default:
none

input

({ as?: "input"; } & Omit<Pick<DetailedHTMLProps<InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, "key" | keyof InputHTMLAttributes<...>> & { ...; }, "children"> & { ...; })
Default:
none

listbox

WithSlotShorthandValue<WithSlotRenderFunction<Omit<ListboxSlots, "root"> & Omit<{ as?: "div"; } & Pick<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "key" | keyof HTMLAttributes<...>> & { ...; } & { ...; }, "ref"> & SelectionProps & RefAttributes<...>>> | null
Default:
none

multiselect

Sets the selection type to multiselect. Set this to true for multiselect, even if fully controlling selection state. This enables styles and accessibility properties to be set.

boolean
Default:
false

onOpenChange

Callback when the open/closed state of the dropdown changes

((e: ComboboxBaseOpenEvents, data: ComboboxBaseOpenChangeData) => void)
Default:
none

onOptionSelect

((event: SelectionEvents, data: OptionOnSelectData) => void)
Default:
none

open

Sets the open/closed state of the dropdown. Use together with onOpenChange to fully control the dropdown’s visibility

boolean
Default:
none

positioning

Configure the positioning of the combobox dropdown

PositioningShorthand
Default:
none

root

WithSlotShorthandValue<{ as?: "div"; } & Pick<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "key" | keyof HTMLAttributes<...>> & { ...; } & { ...; }>
Default:
none

selectedOptions

An array of selected option keys. Use this with onOptionSelect to directly control the selected option(s) If this is set, the value prop MUST also be controlled.

string[]
Default:
none

size

Controls the size of the combobox faceplate

“small” “medium” “large”
Default:
“‘medium’”