Skip to content
Components

Combobox

Searchable select: a button trigger opening a filterable option list in a popover. Works controlled (value + onValueChange) or uncontrolled; supports virtualisation for large lists.

Usage

@instruments/materia-ui/components/combobox

<Field className="w-72">
  <FieldLabel htmlFor="finish-filter">Filter by finish</FieldLabel>
  <FieldContent>
    <Combobox items={FINISHES} placeholder="Any finish…" />
  </FieldContent>
</Field>

Best practices

  • Use Combobox when the user filters/searches a long list; use Select for a short closed list, or a domain variant like CountryCombobox for known sets.

  • onValueChange fires with "" when the current selection is toggled off - treat empty string as "cleared", not as a real value.

  • For lists in the hundreds+, pass virtualization={{ enabled: true }} so only visible rows mount instead of every option.

  • Provide items as { label, value }[] - the visible text comes from label while selection is tracked by value.

Props

PropTypeDefaultDescription
buttonClassNamestring

Button class name

contentClassNamestring

Class name for the popover content panel

data-testidstring

Test id for the trigger button

disabledboolean

Whether disabled

items(required)ComboboxItem[]

List of items

onValueChange(value: string) => void

Called with the selected value, or "" when the selection is toggled off.

placeholderstring"Select…"

Placeholder text

sizeResponsiveSize"xl"

Trigger size - a single token or a per-breakpoint object like { base: "sm", md: "xl" }. Forwarded to the underlying Button.

valuestring

Selected value; provide (with onValueChange) for controlled use, omit for uncontrolled.

virtualizationComboboxVirtualizationOptions

Virtualisation settings for large item sets.

Also exports

  • interfaceComboboxItem
  • interfaceComboboxProps
  • interfaceComboboxVirtualizationOptions

Composition

Builds on

Button, Flex, Icon

Used by

CountryCombobox