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"`	No description
`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. TODO: full JS chip interaction is stubbed — struct + rendered attr only.
`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

Trigger has role="combobox" with aria-expanded and aria-haspopup="listbox". Dropdown list has role="listbox", options have role="option" with aria-selected. Groups have role="group" with aria-label. When auto_highlight is true, the first matching option has data-highlighted and aria-selected="true" for keyboard activation. Search input has aria-label="Search options".