Skip to main content
Combobox is a searchable select — a dropdown that lets users type to filter through options. Useful when the list of choices is large enough that scrolling alone would be tedious.

​
Basic Usage

A Combobox is a container for ComboboxOption children. The label can be passed as a positional argument; the value is what gets stored in state when that option is selected:

​
Reading the Value

Use .rx to get a reactive reference to the selected option’s value string. Embed it in other components to display the current selection: Search for an option and select it — the text updates instantly to show the selected value.

​
Search Placeholder

The search_placeholder parameter customizes the hint text inside the search input that appears when the dropdown opens:

​
With Label

Pair a Combobox with a Label in a Column for a standard form field pattern:

​
Disabled State

A disabled combobox is non-interactive — the trigger button is grayed out and the dropdown won’t open:

​
Disabled Options

Individual options can be disabled while the rest remain selectable. Disabled options still appear in the list but can’t be chosen — useful for options that exist but aren’t currently available:

​
Invalid State

Set invalid=True to indicate a validation error. The trigger shows a red border, making it clear the user needs to correct their selection. Pair it with a Label and error text for a complete form field:

​
Separators

Use ComboboxSeparator to add visual dividers between flat options without needing full group containers. Separators are lightweight — they just draw a line to create logical sections:

​
Option Groups

Organize related options with ComboboxGroup and ComboboxLabel. Each group gets a non-selectable header label, and groups are automatically separated by dividers in the dropdown:

​
Actions

The on_change parameter fires actions when the selection changes. Inside the action, $event holds the newly selected value string: This is different from .rx — here we’re transforming the value before storing it (prepending “Boarding: ”). For simple “show the current selection” cases, .rx is the better approach.

​
Side and Align

Control where the dropdown appears relative to the trigger with side and align. This is useful when the combobox is near the edge of a viewport or inside a constrained layout:

​
API Reference

Combobox Parameters

​
placeholder
str | None
default:"None"
Text shown when no value is selected.
​
search_placeholder
str | None
default:"None"
Placeholder text in the search input.
​
name
str | None
default:"None"
State key for the selected value.
​
disabled
bool
default:"False"
Whether the combobox is non-interactive.
​
invalid
bool
default:"False"
Whether the combobox is in an error state.
​
side
'top' | 'right' | 'bottom' | 'left' | None
default:"None"
Which side to show the dropdown.
​
align
'start' | 'center' | 'end' | None
default:"None"
Alignment of the dropdown relative to the trigger.
​
on_change
Action | list[Action] | None
default:"None"
Action(s) to execute when the selection changes. $event is the value string of the selected option.
​
css_class
str | None
default:"None"
Additional Tailwind CSS classes.

ComboboxOption Parameters

​
label
str
required
Display text. Can be passed as a positional argument.
​
value
str
required
Value stored in state when selected. Defaults to a kebab-case version of the label.
​
disabled
bool
default:"False"
Whether this option is non-selectable.

ComboboxGroup Parameters

Container for grouping related options. Children should be ComboboxLabel and ComboboxOption components.

ComboboxLabel Parameters

​
label
str
required
Label text. Can be passed as a positional argument.

ComboboxSeparator Parameters

Visual divider between options. No parameters.

​
Protocol Reference

Combobox
{
  "type": "Combobox",
  "children?": "[Component]",
  "let?": "object",
  "name?": "string",
  "placeholder?": "string",
  "searchPlaceholder?": "string",
  "disabled?": false,
  "side?": "'top' | 'right' | 'bottom' | 'left'",
  "align?": "'start' | 'center' | 'end'",
  "invalid?": false,
  "onChange?": "Action | Action[]",
  "cssClass?": "string"
}
ComboboxOption
{
  "type": "ComboboxOption",
  "value": "string (required)",
  "label": "string (required)",
  "disabled?": false,
  "cssClass?": "string"
}
ComboboxGroup
{
  "type": "ComboboxGroup",
  "children?": "[Component]",
  "cssClass?": "string"
}
ComboboxLabel
{
  "type": "ComboboxLabel",
  "label": "string (required)",
  "cssClass?": "string"
}
ComboboxSeparator
{
  "type": "ComboboxSeparator",
  "cssClass?": "string"
}
For the complete protocol schema, see Combobox, ComboboxOption.