Multiselect

Put the multiselect in a Field to give it a label, helper, and error. Without a Field, set aria-label; otherwise it has no name at all.

Anatomy

Variants

• field (default): a form field with chips. Name it with a Field or aria-label.
• filter: a compact button for a filter bar. It reads "Status" until something is chosen, then "Status (2)", and gets a tinted fill. The choices live in the menu; there are no chips. filter-label is required: it is the visible text and the accessible name. Don't put a filter in a Field.

Searchable

searchable adds a text input that filters the menu as people type, the same way a Combobox does. Use it for long lists. A loadOptions loader turns it on. The filter variant can't be searchable.

Sizes

With chips, the field's leading padding shrinks to space-4 so the chips line up with its edge. Chips wrap and the field grows; set max-rows to stop at about that many rows and scroll the rest.

States

Hover doesn't change the field. Keyboard focus colors its border and thickens it; there is no ring. While a chip has focus, the chip shows the ring instead. The filter variant tints on hover and shows a focus ring.

• disabled: can't be focused or opened, and isn't submitted. Chips can't be removed.
• readonly: shows the chips and submits them. The field stays focusable, but the menu doesn't open, chips can't be removed, and the clear-all button and chevron are hidden.
• Error: set error on the Field. The message appears below and the border turns red, even while focused. The filter variant never turns red.

Selection limit

max caps how many options people can choose. At the cap, the other options are disabled and the menu says "You can choose up to 2." Chosen options can still be removed.

Options and data

• Write options as <option> children, with <optgroup> for groups. selected sets the starting choices.
• data-description adds a short second line in the menu; chips show the label only.
• Options can also come from the options property or a loadOptions loader, as in Combobox. A loader always shows the search input.
• creatable adds a Create "…" row when a search matches nothing; choosing it adds a new chip. It follows the Combobox rules and stops at max.

When to use

• Use a multiselect when people can pick several options from a list too long to show in full.
• Use a Checkbox group for a short set that fits on screen. It is simpler and shows every option.
• Use a Select or Combobox when people pick exactly one.

Content

• Label: name what you're asking for, in sentence case, with no colon.
• Placeholder: "Choose…". It disappears once something is chosen, so don't put anything people need in it.
• Options: one short line each, in an order people can guess. Put the distinguishing word first. Don't start them with an icon or emoji.
• Limit: if you set max, say so in the helper: "Choose up to 3".
• Error: say how to fix it, using the label's words: "Choose at least one topic".

More in Errors.

Do / Don't

Related

• Field: the label, helper, and error around a multiselect.
• Checkbox group: a short set, all visible.
• Select: one option from a short list; it has the same filter variant.
• Combobox: one option from a long list, with the same filtering.
• Tag: the chip a multiselect uses.
• Select family: how these compare.

API

Attributes

Properties

Slots

Events

change fires when someone checks or unchecks an option, removes a chip, clears all, or creates an option. It doesn't fire when you set value in code. Read the new value from value.

In a form, each chosen value submits under name, like a checkbox group, and a form reset restores the starting choices.

CSS

• ::part(field): the field, or the button in the filter variant.
• ::part(listbox): the menu.

Tokens

The field, menu, options, error, and focus use Select's tokens; the chips are gray Tags; the clear-all button matches the Combobox clear button. Only these differ:

Accessibility

Built in:

• Screen readers hear a combobox with a multi-select list. Each option reads as selected or not, and a hidden status message announces the total, such as "2 selected.", after each change.
• One Tab stop. Chips aren't Tab stops; people reach them with the arrow keys.
• Each chip's remove button is named "Remove" plus the option, such as "Remove Red".
• The clear-all button is named "Clear all". It isn't a Tab stop; from the keyboard, remove chips one by one.
• The menu stays open while people choose, and Esc never changes the choice.
• The menu stays on screen when zoomed. Every row is at least 32px tall.

Your part:

• Give every multiselect a name: a Field label, aria-label, or filter-label.
• If there is a limit, set max and say it in the helper.
• Write errors as the Content rules say.

On a chip: Left / Right move between chips, Right past the last returns to the field, Home jumps to the first chip, End returns to the field, and Delete or Backspace removes the chip.

Contrast limits

• Field border: 1.33:1 in light and 2.00:1 in dark, under the 3:1 minimum; 4.22:1 in high contrast. Always show a label.
• Placeholder: 3.26:1 in light, under the 4.5:1 text minimum. Don't put anything people need in it.