Combobox

A searchable single-select with virtual focus, local and parent-owned filtering, loading states, and collision-aware positioning.

Installation

tsx

import { Combobox } from "madagent";

const options = [
  { value: "draft", label: "Draft" },
  { value: "approved", label: "Approved" },
];

<Combobox options={options} aria-label="Status" />

Default

Controlled and Clearable

Value: amina

Rich Options

Sizes

Parent-Filtered Async Mode

Loading, Empty, and Disabled

Prop	Type	Default	Description
`options*`	`ComboboxOption[]`	-	Options with value, label, and optional description, icon, and disabled state.
`value`	`stringnull`	-	Controlled selected value.
`defaultValue`	`stringnull`	`null`	Initial selected value for uncontrolled usage.
`onChange`	`(value: string \| null) => void`	-	Called when an option is selected or the value is cleared.
`query`	`string`	-	Controlled text input value.
`onQueryChange`	`(query: string) => void`	-	Called as the user types. Its presence enables async mode, so the parent owns filtering.
`loading`	`boolean`	`false`	Replaces options with a loading status row.
`placeholder`	`string`	`"Select an option"`	Input placeholder shown when there is no value or query.
`size`	`"sm""md""lg"`	`"md"`	Controls the input height and text scale.
`disabled`	`boolean`	`false`	Disables typing and opening the listbox.
`clearable`	`boolean`	`false`	Shows a small clear button when a value or query is present.
`emptyMessage`	`ReactNode`	`"No options found"`	Content rendered when the filtered option list is empty.
`filter`	`(option: ComboboxOption, query: string) => boolean`	-	Overrides case-insensitive local filtering in synchronous mode.

RTL Support

Components automatically adapt to right-to-left languages using CSS logical properties.

Preview

Usage

tsx

<Combobox
  options={[
    { value: "cairo", label: "القاهرة", description: "المكتب الرئيسي" },
    { value: "riyadh", label: "الرياض", description: "فرع المملكة" },
    { value: "dubai", label: "دبي", description: "مركز التوزيع" },
  ]}
  defaultValue="cairo"
  clearable
  aria-label="المدينة"
/>

Prop

Type

Default

Description

options*

ComboboxOption[]

Options with value, label, and optional description, icon, and disabled state.

value

stringnull

Controlled selected value.

defaultValue

stringnull

null

Initial selected value for uncontrolled usage.

onChange

(value: string | null) => void

Called when an option is selected or the value is cleared.

query

string

Controlled text input value.

onQueryChange

(query: string) => void

Called as the user types. Its presence enables async mode, so the parent owns filtering.

loading

boolean

false

Replaces options with a loading status row.

placeholder

string

"Select an option"

Input placeholder shown when there is no value or query.

size

"sm""md""lg"

"md"

Controls the input height and text scale.

disabled

boolean

false

Disables typing and opening the listbox.

clearable

boolean

false

Shows a small clear button when a value or query is present.

emptyMessage

ReactNode

"No options found"

Content rendered when the filtered option list is empty.

filter

(option: ComboboxOption, query: string) => boolean

Overrides case-insensitive local filtering in synchronous mode.

RTL Support

Components automatically adapt to right-to-left languages using CSS logical properties.

Preview

Usage

tsx

<Combobox
  options={[
    { value: "cairo", label: "القاهرة", description: "المكتب الرئيسي" },
    { value: "riyadh", label: "الرياض", description: "فرع المملكة" },
    { value: "dubai", label: "دبي", description: "مركز التوزيع" },
  ]}
  defaultValue="cairo"
  clearable
  aria-label="المدينة"
/>