A button that opens a searchable list of options to choose one value from.
Selector: mui-combobox
Import
import { Combobox, ComboboxItem } from '@mushilu-san/ui/overlays';
PreviewCode
Loading example…
Overview
Combobox shows the chosen value in a trigger button and opens a role="listbox" panel of mui-combobox-item options. value is a two-way model that holds the chosen item value.
Escape closes the panel and returns focus to the trigger. Use it when the list is too long for a native select.
When to use
Choosing one value from a long list, such as a country, a user or a product.
Lists where users know part of the name.
When not to use
A short fixed list. Use a select, which is simpler and works natively on phones. Use Select instead.
Running a command. Use a command palette. Use Command instead.
Guidelines
Do
Give the trigger a label that names the field.
Show the chosen value in the trigger so the choice is visible.
Don't
Do not use a combobox for two or three options. Use radio buttons or a select.
Accessibility
Roles and attributes
Element
Role
Notes
trigger
button with aria-haspopup="listbox"
aria-expanded follows the panel.
panel
listbox
Options are role="option", with aria-selected on the chosen one.
Keyboard
Keys
Action
EnterSpace
Opens the panel on the trigger.
Escape
Closes the panel and returns focus to the trigger.
Label the trigger with the field name. The chosen value is announced when the panel closes.
API
Combobox
Selector: mui-combobox
Name
Type
Default
Description
placeholder
string
'Select…'
Text shown in the trigger when nothing is chosen. Default `Select…`.
disabled
boolean
false
Disables the trigger. Accepts attribute presence, e.g. <… disabled>.
Name
Type
Default
Description
value
string
''
Value of the chosen item. Two-way bindable with `[(value)]`.
Name
Type
Description
opened
void
Emits when the panel opens.
closed
void
Emits when the panel closes.
CSS parts
::part(list)
::part(panel)
::part(root)
::part(search)
::part(search-wrapper)
::part(trigger)
ComboboxItem
Selector: mui-combobox-item
Name
Type
Default
Description
valuerequired
string
—
Value this option represents. Written to the combobox's `value` model when chosen.
disabled
boolean
false
Disables this option. It cannot be chosen. Accepts attribute presence, e.g. <… disabled>.
Mushilu-San UI