Combobox

Filterable select with search, single and multi-select, grouping, and chips.

Interactive-mode

Divergence from Blok

Blazor-idiomatic bindings (paradigm translation, not a behavioural divergence). Blok wraps @base-ui/react/combobox which exposes React state hooks. BlazorUI's port surfaces the same state through @bind-Value (single) or @bind-Values (multi) and @bind-InputValue for the filter text. React's useComboboxAnchor hook has no Blazor equivalent — use @ref on a plain element if you need to anchor the popover somewhere other than the input or chips wrapper.

Known gaps. Keyboard navigation supports Arrow Up/Down, Enter, and Escape. Advanced behaviours from @base-ui (Home/End jumps, typeahead buffering, tap-to-open on mobile pointer-coarse devices) are not yet ported.

Examples

Default

Clear button

Groups

With descriptions

Multi-select with chips

Input group (decorated input)

Disabled

API

The element family below can be composed together. Click an element to jump to its properties.

Element	Purpose
Combobox	Root state container. Holds the single (`Value`) or multi (`Values`) selection, the filter text (`InputValue`), and the open/highlight state; cascades itself so descendants can read and mutate that state.
ComboboxInput	Decorated text input used as the combobox anchor in single-select mode. Wraps an `InputGroup` with a chevron/clear button and forwards keystrokes to `Combobox.HandleKeyDown`.
ComboboxChips	Wrapper used as the combobox anchor in multi-select mode. Hosts one `ComboboxChip` per selected value plus a `ComboboxChipsInput` for typing the filter.
ComboboxChip	Pill rendered for a single selected value in multi-select mode. Resolves its label from the `Combobox` label cache and optionally shows an ✕ remove button.
ComboboxChipsInput	The `<input>` that sits inside `ComboboxChips` and captures filter text in multi-select mode.
ComboboxContent	The popup container for the filtered list. Always mounted (hidden via `display:none`) so `ComboboxItem` instances can register their labels even before the dropdown opens.
ComboboxList	Scrollable container for the option rows. Tracks child `ComboboxGroup` / `ComboboxItem` / `ComboboxSeparator` registration so separators can hide themselves when stranded.
ComboboxGroup	Groups related items under a `ComboboxLabel`. Registers its items so the label can hide itself when every child is filtered out.
ComboboxLabel	Non-interactive heading for a `ComboboxGroup`. Automatically hidden when its parent group has no items matching the current filter.
ComboboxItem	A selectable option row. Registers with the parent `Combobox` and (optional) `ComboboxGroup`, and matches the current filter on its `Value` or `Label`.
ComboboxItemText	Two-line text container placed inside a `ComboboxItem`. Holds a `ComboboxItemTitle` and a `ComboboxItemDescription`.
ComboboxItemTitle	Primary line inside a `ComboboxItemText`. Rendered in semibold.
ComboboxItemDescription	Secondary line inside a `ComboboxItemText`. Rendered in a muted colour at smaller type.
ComboboxSeparator	Decorative divider between groups. Hides itself automatically when it would be stranded (first, last, or stacked next to another visible separator).
ComboboxEmpty	Placeholder rendered when no items match the current filter. Uses CSS `:has()` to hide itself whenever at least one item is visible.
ComboboxTrigger	Alternative button-style anchor (dropdown trigger). Toggles the popup and inherits the chevron affordance.
ComboboxValue	Read-only display of the current single-select label, with a fallback placeholder. Use inside a `ComboboxTrigger` when you don't want a text input.
ComboboxCollection	Generic helper for binding a collection to the list. Iterates `Items` and renders `ItemTemplate` for each — lets you stamp out `ComboboxItem` rows from a data source without a hand-written `@foreach`.

Combobox

Root state container. Holds the single (Value) or multi (Values) selection, the filter text (InputValue), and the open/highlight state; cascades itself so descendants can read and mutate that state.

Property	Type	Description
Value	string?	Selected value in single-select mode. Supports two-way binding via `@bind-Value`.
ValueChanged	EventCallback<string?>	Fires whenever `Value` changes. Pair with `Value` for two-way binding.
Values	List<string>	Selected values in multi-select mode. Supports two-way binding via `@bind-Values`. Default: empty list.
ValuesChanged	EventCallback<List<string>>	Fires whenever `Values` changes. Pair with `Values` for two-way binding.
Multiple	bool	Enables multi-select mode. Pair with `Values`/`ValuesChanged` and a `ComboboxChips` wrapper. Default: `false`.
InputValue	string?	Filter text typed into the input. Items are matched against `Value` and `Label`. Supports two-way binding via `@bind-InputValue`.
InputValueChanged	EventCallback<string?>	Fires whenever `InputValue` changes. Pair with `InputValue` for two-way binding.
Disabled	bool	Disables the whole combobox (input, trigger, items). Default: `false`.
ChildContent	RenderFragment?	Should contain a `ComboboxInput` (or `ComboboxChips`) and a `ComboboxContent`.

ComboboxInput

Decorated text input used as the combobox anchor in single-select mode. Wraps an InputGroup with a chevron/clear button and forwards keystrokes to Combobox.HandleKeyDown.

Property	Type	Description
Placeholder	string?	Placeholder text shown when no value is selected and no filter is typed.
ShowTrigger	bool	When true, renders the chevron toggle button. Hidden automatically when a clear button is visible. Default: `true`.
ShowClear	bool	When true, renders an ✕ button that clears the selection and filter. Default: `false`.
Disabled	bool	Disables the input independently of the parent `Combobox.Disabled`. Default: `false`.
Name	string?	Forwarded as the `<input>` `name` attribute for form submission.
ClassName	string?	Extra CSS classes appended to the outer `InputGroup`.
ChildContent	RenderFragment?	Slot for `InputGroupAddon` decorations (leading icons, trailing buttons).
AdditionalAttributes	Dictionary<string, object>?	Captured unmatched attributes, forwarded to the underlying `<input>`.

ComboboxChips

Wrapper used as the combobox anchor in multi-select mode. Hosts one ComboboxChip per selected value plus a ComboboxChipsInput for typing the filter.

Property	Type	Required	Description
ClassName	string?		Extra CSS classes appended to the chips wrapper.
ChildContent	RenderFragment?		Should contain a `ComboboxChip` per selected value and a `ComboboxChipsInput`.

ComboboxChip

Pill rendered for a single selected value in multi-select mode. Resolves its label from the Combobox label cache and optionally shows an ✕ remove button.

Property	Type	Description
Value	string	The value this chip represents. Clicking ✕ removes it from `Combobox.Values`.
ShowRemove	bool	Whether to render the ✕ remove button. Default: `true`.
ClassName	string?	Extra CSS classes appended to the chip.
ChildContent	RenderFragment?	Override the chip's label content. When omitted, the resolved label for `Value` is rendered.

ComboboxChipsInput

The <input> that sits inside ComboboxChips and captures filter text in multi-select mode.

Property	Type	Description
Placeholder	string?	Placeholder text shown when no chips are present and no filter is typed.
Disabled	bool	Disables the input. Default: `false`.
Name	string?	Forwarded as the `<input>` `name` attribute for form submission.
ClassName	string?	Extra CSS classes appended to the input.
AdditionalAttributes	Dictionary<string, object>?	Captured unmatched attributes, forwarded to the underlying `<input>`.

ComboboxContent

The popup container for the filtered list. Always mounted (hidden via display:none) so ComboboxItem instances can register their labels even before the dropdown opens.

Property	Type	Required	Description
ClassName	string?		Extra CSS classes appended to the popup container.
ChildContent	RenderFragment?		Should contain a `ComboboxList` and optionally a `ComboboxEmpty`.

ComboboxList

Scrollable container for the option rows. Tracks child ComboboxGroup / ComboboxItem / ComboboxSeparator registration so separators can hide themselves when stranded.

Property	Type	Required	Description
ClassName	string?		Extra CSS classes appended to the list element.
ChildContent	RenderFragment?		Items, groups, and separators.

ComboboxGroup

Groups related items under a ComboboxLabel. Registers its items so the label can hide itself when every child is filtered out.

Property	Type	Description
Disabled	bool	When true, disables every `ComboboxItem` inside this group (item-level `Disabled` is unioned with this). Default: `false`.
ClassName	string?	Extra CSS classes appended to the group wrapper.
ChildContent	RenderFragment?	Should contain a `ComboboxLabel` followed by `ComboboxItem` rows.

ComboboxLabel

Non-interactive heading for a ComboboxGroup. Automatically hidden when its parent group has no items matching the current filter.

Property	Type	Required	Description
ClassName	string?		Extra CSS classes appended to the label.
ChildContent	RenderFragment?		Label text.

ComboboxItem

A selectable option row. Registers with the parent Combobox and (optional) ComboboxGroup, and matches the current filter on its Value or Label.

Property	Type	Description
Value	string?	The value this item represents. Returned via `Value`/`Values` when selected.
Label	string?	Display text shown in the popup and cached for `ComboboxChip` / selected-label rendering.
Disabled	bool	Disables this item independently of its group/combobox. Default: `false`.
ClassName	string?	Extra CSS classes appended to the item element.
ChildContent	RenderFragment?	Custom item body (use with `ComboboxItemText`/`ComboboxItemTitle`/`ComboboxItemDescription`). When omitted, the `Label` or raw `Value` is rendered.

ComboboxItemText

Two-line text container placed inside a ComboboxItem. Holds a ComboboxItemTitle and a ComboboxItemDescription.

Property	Type	Required	Description
ClassName	string?		Extra CSS classes appended to the text column.
ChildContent	RenderFragment?		Should contain `ComboboxItemTitle` and `ComboboxItemDescription`.

ComboboxItemTitle

Primary line inside a ComboboxItemText. Rendered in semibold.

Property	Type	Required	Description
ClassName	string?		Extra CSS classes appended to the title.
ChildContent	RenderFragment?		Title text.

ComboboxItemDescription

Secondary line inside a ComboboxItemText. Rendered in a muted colour at smaller type.

Property	Type	Required	Description
ClassName	string?		Extra CSS classes appended to the description.
ChildContent	RenderFragment?		Description text.

ComboboxSeparator

Decorative divider between groups. Hides itself automatically when it would be stranded (first, last, or stacked next to another visible separator).

Property	Type	Required	Description
ClassName	string?		Extra CSS classes appended to the separator.

ComboboxEmpty

Placeholder rendered when no items match the current filter. Uses CSS :has() to hide itself whenever at least one item is visible.

Property	Type	Required	Description
ClassName	string?		Extra CSS classes appended to the empty-state element.
ChildContent	RenderFragment?		Message to display when no items match.

ComboboxTrigger

Alternative button-style anchor (dropdown trigger). Toggles the popup and inherits the chevron affordance.

Property	Type	Description
Disabled	bool	Disables the trigger button. Default: `false`.
ClassName	string?	Extra CSS classes appended to the `<button>`.
ChildContent	RenderFragment?	Trigger label — typically a `ComboboxValue`.
AdditionalAttributes	Dictionary<string, object>?	Captured unmatched attributes, forwarded to the underlying `<button>`.

ComboboxValue

Read-only display of the current single-select label, with a fallback placeholder. Use inside a ComboboxTrigger when you don't want a text input.

Property	Type	Required	Description
Placeholder	string?		Muted text shown when no value is selected.
ChildContent	RenderFragment?		Override the displayed content. When omitted, the resolved label for `Value` is rendered.

ComboboxCollection

Generic helper for binding a collection to the list. Iterates Items and renders ItemTemplate for each — lets you stamp out ComboboxItem rows from a data source without a hand-written @foreach.

Property	Type	Required	Description
Items	IEnumerable<TItem>?		Source collection. Each element is passed to `ItemTemplate`.
ItemTemplate	RenderFragment<TItem>?		Template rendered once per item. Typically produces a `ComboboxItem`.