Combobox

Anatomy

A searchable select component with optional grouping, multi-select mode, and auto-highlight. Extends Select with text filtering and chip rendering for multi-select.

maud_ui::primitives::combobox

Props

Generated from public Rust fields. Defaults are evaluated from the implementation.

Prop	Type	Default	Description
`id`	`String`	`"combobox"`	No description
`name`	`String`	`"combobox"`	Form field name. Multiple selections submit repeated `name[]` entries.
`options`	`Vec<ComboboxOption>`	`[]`	No description
`selected`	`Option<String>`	`None`	No description
`placeholder`	`String`	`"Select…"`	No description
`search_placeholder`	`String`	`"Search…"`	No description
`empty_text`	`String`	`"No results found."`	No description
`disabled`	`bool`	`false`	No description
`multiple`	`bool`	`false`	Multi-select mode. When true, selected values render as chips in the trigger.
`auto_highlight`	`bool`	`false`	When true, the first filtered option gets `aria-selected="true"` and `data-highlighted` so keyboard Enter can commit it immediately.
`show_clear`	`bool`	`false`	Render a small X button inside the trigger to clear the selection.
`aria_invalid`	`bool`	`false`	Sets `aria-invalid="true"` on the trigger for form-validation styling.
`groups`	`Vec<ComboboxGroup>`	`[]`	Grouped options. When non-empty, takes precedence over `options` and renders group labels as `.mui-combobox__group-label`.
`selected_values`	`Vec<String>`	`[]`	Selected values for multi-select mode (rendered as chips).

Examples

Framework picker

Search and select from a list of frontend frameworks.

Pre-selected

Placeholder

Disabled

Auto-highlight

With clear button

Invalid state

Assign team member

A realistic search-to-select pattern for assigning people to a task.

Lead

Reviewer

Optional. The reviewer will be notified when the task is ready.

Watchers (multi)

Grouped options

Options separated into logical groups with uppercase labels.

Usage and composition

Import

use maud_ui::primitives::combobox::{self, ComboboxOption, ComboboxGroup, Props};

Example

use maud::html;
use maud_ui::primitives::combobox;

html! {
    (combobox::render(combobox::Props {
        id: "framework".into(),
        name: "framework".into(),
        options: vec![
            combobox::ComboboxOption { value: "react".into(), label: "React".into() },
            combobox::ComboboxOption { value: "vue".into(), label: "Vue".into() },
        ],
        selected: Some("react".into()),
        placeholder: "Select...".into(),
        search_placeholder: "Search...".into(),
        empty_text: "No results.".into(),
        disabled: false,
        multiple: false,
        auto_highlight: true,
        show_clear: true,
        aria_invalid: false,
        groups: vec![],
        selected_values: vec![],
    }))
}

Shadcn reference

https://ui.shadcn.com/docs/components/base/combobox

Accessibility

In Nova, the editable input has role="combobox", aria-expanded, aria-controls, and list autocomplete. Standard retains a focusable combobox trigger and a search input in the popup. Options expose their selected state with aria-selected; auto_highlight highlights the first match without changing its selection. Groups have role="group" with an accessible label.

The Nova option list fits the available viewport space and updates its placement when the page scrolls or resizes. Keyboard navigation scrolls the active option into view with the same inset as the pinned list recipe. The popup stays transparent until its initial position is resolved. Nova option highlighting updates immediately without a background-color transition.

Single selection submits one value under name; multiple selection submits one value per selected chip under name[]. Disabled controls do not submit. A committed change or clear emits mui-combobox-change with detail.value as a string or array. Native form reset restores the initial selection when form-associated custom elements are supported. Its private nameless readonly reset helper appears in form.elements but contributes no submitted value; older browsers use a deferred fallback with limited late-cancellation fidelity.