- Multi Select includes Default, Hover, Focus, Focus Visible, and Locked states.
- Focus Visible is triggered by keyboard navigation using the Tab key.
- Focus is shown while the Multi Select is open with a mouse click.
- The Invalid validation state can only have Default and Hover states. When the user clicks on an Invalid Multi Select, the validation is cleared and the component transitions to the Focus state. Pressing Tab instead transitions it to the Focus Visible state.
Multiselect
Molecule
The Multi Select Component is a form input component used to allow users to make one or more selections from a list of options. It supports two display modes: Lozenges, where selected options appear as individual chips with an overflow indicator, and Searchable Counter, which shows a summary count when closed and a search field when open for filtering options.
The list of options can behave in two ways: Static – selected options remain in their original position in the list. Selected on top – selected options are automatically moved to the top of the list, separated from unselected ones by a Divider. Both groups are sorted alphabetically. This behavior cannot be prototyped in Figma.
Playground
TheAppWrapper is set to max-width: 380px
Multiselect component
<
Multiselect
options
=
"[
{
"value": 1,
"text": "Option 1 is a very long option, so we can check whether truncation works with it",
"isDisabled": false
},
{
"value": 4,
"text": "N/mm<sup>2</sup>",
"isDisabled": false,
"hasAction": true
},
{
"value": 7,
"text": "Option 7",
"isDisabled": false
},
{
"value": 2,
"text": "Option 2",
"isDisabled": true
},
{
"value": 5,
"text": "Option 5",
"isDisabled": false,
"isIndeterminate": true
},
{
"value": 3,
"text": "Option 3",
"isDisabled": false
},
{
"value": 6,
"text": "Option 6",
"isDisabled": false
}
]"
animateGrouping
checkboxPosition
=
"leading"
label
=
"Label"
placeholder
=
"Select an option"
labelCategory
=
"large"
noOfOptionsToShow
searchOptions
=
"{
"enableSearch": false,
"caseSensitive": false,
"placeholder": "",
"summaryText": ""
}"
/>
ModelValues
For more information on ModelValues please have a look to the Vue's Data Binding section.
ts
const modelValue = defineModel<T[] | null>('modelValue', { required: true });
const searchString = defineModel<string>('searchString', { default: '' });Properties
ts
/**
* Multiselect public props = Select field surface, with array `modelValue` and Multiselect-only knobs.
* Does not expose Select `groupDisabledOptions` (use `groupBy` instead).
*/
export interface MultiselectGenericProps<T extends string | number = string | number> extends
Omit<SelectPublicProps<T>, 'modelValue' | 'options' | 'groupDisabledOptions' | 'validation'> {
modelValue: T[] | null;
options: MultiselectOptionGeneric<T>[];
validation?: SelectFamilyValidation;
/**
* Partition the list:
* - `disabled`: enabled first, disabled second
* - `selected`: selected (from `modelValue`) first; alphabetical + animated by default
*/
groupBy?: 'disabled' | 'selected';
checkboxPosition?: 'leading' | 'trailing';
/** Animate group moves when `groupBy` is `selected`. Default: true */
animateGrouping?: boolean;
}ts
export interface MultiselectOptionGeneric<T extends string | number> extends SelectOptionGeneric<T> {
/**
* @deprecated Selection is derived from `modelValue` only. Not read or written at runtime.
*/
isSelected?: boolean;
isIndeterminate?: boolean;
}ts
export type MultiselectActionGeneric<T extends string | number> = SelectActionGeneric<T>;Anatomy
- Form Label - Tells the user what they are selecting for and indicates if selection is required. Can be hidden.
- Select Field - This is where the selected options are displayed using Lozenges. Can be individual Lozenges or a summary Lozenge. It changes state when hovered, focused or locked. Placeholder text is displayed when no selections have been made yet. For Searchable type, when the menu is opened, a search Icon and Placeholder text appears and the user can type to search through options.
- Lozenges - representing the selected options.
- Icon (Chevron Down/Up) - Indicates whether the option list is closed or open. Switches to Chevron Up when clicked and the menu is opened.
- HelpText - Additional instruction to the user regarding the selection. Also can be hidden.
- Option List — containing the options which can be selected. In Figma there can be 2-10 custom options, but in practice there can of course be more. The height is set to hug with a max height of 192px so that when there are more than 6 options, it will scroll. It can open up or down to maintain readability at various locations on screen.
- Checkboxes - representing each option that can be selected. Multiple options can be selected at a time.
States
Variants
Display
- Defines how selected options are displayed inside the component.
- No Selection — No options have been selected yet. Placeholder text is shown.
- Lozenges — Each selected option is represented as an individual chip. If all selected options do not fit, the overflow is indicated by a counter chip (e.g. "+3").
- Searchable — When closed, displays a single lozenge summarizing the number of selected options. When open, the summary is replaced by a search field for filtering options in the dropdown.
Menu
- Can be open or closed.
Menu Direction
- The option list can open Down or Up to maintain readability at various locations on screen.
Form Label
- Show or hide Form Label.
HelpText + Validation
- Show or hide HelpText.
- The Multi Select supports two validation states: None and Invalid. When validation is applied, the HelpText communicates the current validation result.
- If the Multi Select has informational HelpText and a validation state is triggered, the validation message replaces the original informational message. Validation feedback always takes priority over informational HelpText.
- Multi Select does not have a Validated state. Its values are predefined, so selecting an available option does not require positive validation feedback.