Form field name; in multiple mode, one entry per value.
value
string
Initial value (comma-separated values in multiple mode); selected as soon as its option exists, even if the options arrive later.
placeholder
string
Field placeholder text.
multiple
boolean
Multiple selection shown as removable chips (Backspace removes the last one).
creatable
boolean
Offers an “Add ‘x’” option when the input matches no option.
free
boolean
Autocomplete mode: the value is the typed text, options are only suggestions.
clearable
boolean
Clear button once a value is chosen.
required
boolean
Native validation (valueMissing).
disabled
boolean
Disables the field.
invalid
boolean
Error style + aria-invalid.
loading
boolean
Shows “Loading…” with a spinner in the list (async sources).
empty-text
string
No results
Message when nothing matches.
create-text
string
Add “{query}”
Label of the create option.
placement
bottom-start | top-start…
bottom-start
List placement (flipped when there is no room).
label
string
Accessible name without a <label for>.
data-size
sm | lg
Field height.
Properties
Name
类型
Description
value
string
Value (or text in free mode); in multiple mode, values joined by commas. A value set before its option exists is applied when the option arrives, unless the user has picked something in between.
Option source, added after the child <option>s (an option whose value is already a child is skipped). Setting it keeps the child options.
selectedOptions
object[]
Selected options (read-only).
isOpen
boolean
Whether the list is open (read-only).
Methods
Name
Description
open() / close()
Opens or closes the list.
clear()
Clears the selection.
addOption(option)
Adds an option.
focus()
Focuses the field.
checkValidity() / reportValidity()
Native validation.
Events
Name
Description
mv-change
detail: { value, values, option }.
mv-query
detail: { query } on every keystroke (to load remote options).
mv-create
Cancelable; detail: { value, label } before an option is created.
mv-open / mv-close
List opened and closed.
Content structure
Name
Description
<option> / <optgroup>
Declarative options (value, label, disabled, selected, data-hint, data-keywords). They stay in the DOM, hidden, and are watched: options added, removed or edited later (Angular @for, Vue v-for, React lists) update the list.
[data-start]
Icon placed at the start of the field (also when rendered after the element connects).
APG “Combobox with listbox popup” pattern: input role=combobox, aria-expanded, aria-controls, aria-autocomplete=list and aria-activedescendant (focus stays in the field). ↓/↑ open and navigate, Alt+↓ opens, Page Up/Down jump by 10, Enter selects, Escape closes then clears, Backspace removes the last chip. List role=listbox (aria-multiselectable in multiple mode), labeled role=group groups, options with aria-selected / aria-disabled. Result count and additions are announced through a polite live region.