Combobox

An autocomplete input with a filterable dropdown list.

Installation

dotnet add package Lumeo

One-time app setup (AddLumeo(), CSS & JS) is covered in the installation guide.

Usage

@using Lumeo

<Combobox />

Default

Country Selector

Country

With Label

Language

Multiple Selection

Selected: none

Clearable + MaxDisplayTags (Multiple)

First 2 selections show as chips; the rest collapse to "+N more". The × button clears all.

Grouped Items

Selected: none

Collapsible Groups + Group Select

Selected: none

Data-bound mode still needs the panel children. When you pass Items you must still place <ComboboxInput /> and <ComboboxContent /> inside the <Combobox> — they render the input and the dropdown panel the bound items fill. A bare <Combobox Items="…" /> with no children has nothing to render into and shows an empty field. The same applies to Select with <SelectTrigger /> + <SelectContent />.

Items with Icons + Descriptions (data-bound)

Async Search

API Reference

Combobox

Property	Type	Default	Description
Value	string?	null	The currently selected value. Use with @bind-Value for two-way binding.
ValueChanged	EventCallback<string>	—	Callback invoked when the selected value changes.
Open	bool	false	Controls whether the dropdown is open. Use with @bind-Open for two-way binding.
OpenChanged	EventCallback<bool>	—	Callback invoked when the open state changes.
Required	bool	false	Marks the field as required. Syncs with a parent FormField.
Invalid	bool	false	Applies error styling. Syncs with a parent FormField.
ErrorText	string?	null	Error message displayed below the field when Invalid is true.
HelperText	string?	null	Helper text shown below the field when not invalid.
Label	string?	null	Label rendered above the field (standalone, without FormField).
Name	string?	null	HTML name attribute for form submission.
Class	string?	null	Custom CSS classes merged onto the Combobox's wrapper element.
Placeholder	string?	null	Convenience placeholder shown by ComboboxInput — a top-level alternative to `<ComboboxInput Placeholder="…">`. The input's own Placeholder wins if both are set.
AdditionalAttributes	Dictionary<string, object>?	null	Unmatched attributes are forwarded to the wrapper element.
FormField	FormField.FormFieldContext?	null	Cascaded context from a parent FormField; wires label, validation, and required state automatically.
IsOpen	bool	false	Obsolete alias for `Open`; forwards to and from it.
IsOpenChanged	EventCallback<bool>	—	Obsolete alias for `OpenChanged`; forwards to and from it.
Items	IEnumerable<object>?	null	Optional data source. When set, ComboboxContent renders options from this list instead of ChildContent.
ItemDescription	Func<object, string?>?	null	Optional secondary line per item, rendered below the label in muted text. Return null per item to suppress the sub-line. Only applies when ItemTemplate is unset.
ItemIcon	Func<object, RenderFragment?>?	null	Optional leading icon per item (typically a Blazicon). Return null per item to skip the icon column entirely so iconed and un-iconed rows can mix. Only applies when ItemTemplate is unset.
ItemTemplate	RenderFragment<object>?	null	Optional custom render fragment for an item's content. Receives the raw item object. When set, ItemIcon / ItemDescription are not used (template wins).
Virtualize	bool	false	When true and Items is set, uses Blazor's Virtualize component for the option list.
ItemSize	float	36f	Estimated pixel height of each option row used by the Virtualize component.

ComboboxInput

Property	Type	Default	Description
Placeholder	string	"Search..."	Placeholder text shown in the search input when empty.

ComboboxItem

Property	Type	Default	Description
Value	string	""	The value this item represents when selected. Required. Also used for filtering against the search text.

Combobox — Additional Props

Property	Type	Default	Description
Multiple	bool	false	When true, allows selecting multiple values at once.
Values	HashSet<string>	new()	The set of selected values when Multiple is true. Use with @bind-Values.
Clearable	bool	false	Shows a × button in the input that resets the selection to empty. Mirrors Select.Clearable.
MaxDisplayTags	int	3	In Multiple mode, caps the number of chips shown in the input — the rest collapse into a "+N more" indicator.
OnSearchAsync	EventCallback<string>	—	Callback invoked (debounced) when the search query changes, enabling server-side filtering.
DebounceMs	int	300	Milliseconds to debounce the OnSearchAsync callback.
IsSearchLoading	bool	false	When true, shows a loading indicator inside the dropdown.
ValuesChanged	EventCallback<HashSet<string>>	—	Two-way binding callback for the multi-select values set.
Creatable	bool	false	When true, users can create new values that are not in the list.
OnCreate	EventCallback<string>	—	Invoked when the user creates a new value via the create affordance.
EmptyText	string?	null	ComboboxContent — text shown when no items match. Defaults to "No results".
ShowCreate	bool	false	ComboboxCreate — toggles the "create new" item visibility.