Multi Select Menu

Input control allowing for choosing multiple options from searchable options menu.

MultiSelectMenu is built on top of Select Menu parts which provide core functionality of the component.

Import#

import { MultiSelectMenu } from '@volue/wave-react';

Multi Select Menu is a compound component that consists of multiple parts:

MultiSelectMenu: The wrapper that contains all the parts of a select menu and provides context for its children.
MultiSelectMenu.Trigger: The button that toggles the select menu.
MultiSelectMenu.Content: A wrapper for the content to be rendered when the select menu is open. It positions itself by aligning over MultiSelectMenu.Trigger.
MultiSelectMenu.Clear: The button that clears the value(s) of select menu.
MultiSelectMenu.Item: A container for select menu's item of choice.
MultiSelectMenu.ItemText: A wrapper around textual part of MultiSelectMenu.Item.
MultiSelectMenu.Group: A wrapper for the group of select menu items.
MultiSelectMenu.Label: The component that renders an accessible label of MultiSelectMenu.Group.
MultiSelectMenu.NestedGroup: A wrapper for the checkbox-like group of select menu items.
MultiSelectMenu.NestedGroupLabel: The component that renders selectable label of MultiSelectMenu.NestedGroup
MultiSelectMenu.Separator: The component that renders a horizontal divider between menu items and groups.

Examples#

Basic#

In contrast with Single Select Menu, the options popup of MultiSelectMenu doesn't close after an item is selected, which enables users to continue choosing more options. MultiSelectMenu items are visually distinct from the Single Select Menu items, to indicate multiple selection.

Provide placeholder prop when the select input does not have an initial value.

MultiSelectMenu has built in typeahead behavior, meaning pressing the letter B will jump to and highlight the word "Banana" in the example below.

With a default value#

When using MultiSelectMenu in "uncontrolled" mode, you can specify the default selected options with defaultValue property.

Controlled#

You can easily make the MultiSelectMenu controlled, by passing your own state to value prop. onValueChange handler is called when the selected value changes, allowing you to sync state.

With a clear button#

Use MultiSelectMenu.Clear part to render a button that clears the value of the select menu. Focus will automatically move back to the select menu trigger after the value is cleared.

MultiSelectMenu.Clear will not render itself when the select menu has no value.

With labels#

You can pass the withLabels prop which will render the selected values as Labels that can be individually removed. This presentation is useful for visually representing multiple active filters.

Disabled#

The component can use isDisabled prop to prevent user from interacting, but also single items can be disabled to limit user's choice.

With Form Field#

Use Form Field component to enhance MultiSelectMenu with: an accessible label, an optional helper text, a feedback message or to show required indicator.

It is recommended to wrap select inputs with Form Field to create a consistent set of accessible form fields.

The Form Field automatically generates a unique id that links the MultiSelectMenu with the FormField.Label.

When using MultiSelectMenu without Form Field, be mindful to provide aria-label for MultiSelectMenu.Trigger.

Sizes#

MultiSelectMenu comes in two size variants: medium and small, with the medium size used by default. All sizes are aligned with sizes of other related components like Text Input.

Customized appearance#

MultiSelectMenu.Trigger can be decorated with supporting icons or elements using startElement and endElement props. MultiSelectMenu.Item can have additional endElement specified.

Groups#

Related options can be grouped together using MultiSelectMenu.Group with MultiSelectMenu.Label as a label for the group.

Notice how overflowing content behaves when there is a long list of select menu items.

When you open the menu, last selected item is focused and scrolled into view if necessary.

Nested groups#

MultiSelectMenu supports nesting of selectable groups through MultiSelectMenu.NestedGroup and MultiSelectMenu.NestedGroupLabel parts.

Partially selected groups are presented as checkboxes with indeterminate state.

Custom render value#

By default, MultiSelectMenu.Trigger will automatically display the selected items text content separated with commas.

However you can take control over the rendering by providing a function to the renderValue prop. The function receives getter for the selected items. The element returned by this function will be rendered inside the trigger.

This can be useful to prevent listing all selected items inside the trigger when the list is long and horizontal space is at a premium.

Notice that renderValue override cannot work together with withLabels prop.

If you return interactive elements i.e. buttons, call stopPropagation() from the onPointerDown event to prevent them from opening the options menu.

HTML Form integration#

MultiSelectMenu automatically uses hidden select part from Select Menu when it's used in the context of an HTML form.

You just need to provide name property that will be used when submitting the form.

Accessibility features#

Exposed to assistive technology as a select-only combobox with a listbox popup using the WAI ARIA Listbox pattern.
Implements proper keyboard support and focus management practices.
Typeahead to allow selecting options by typing text, even without opening the listbox.

API Reference#

MultiSelectMenu#

Prop	Type	Default
`value`	`string[]`	No default value
`defaultValue`	`string[]`	No default value
`onValueChange`	`function`	No default value
`isOpen`	`boolean`	`false`
`defaultIsOpen`	`boolean`	No default value
`onIsOpenChange`	`function`	No default value
`size`	`enum`	`medium`
`isDisabled`	`boolean`	`false`
`isRequired`	`boolean`	No default value
`validationStatus`	`enum`	No default value
`name`	`string`	No default value

MultiSelectMenu.Trigger#

Prop	Type	Default
`as`	`enum`	`div`
`css`	`StitchesCss`	No default value
`withLabels`	`boolean`	`false`
`startElement`	`React.ReactElement`	No default value
`endElement`	`React.ReactElement`	No default value
`renderValue`	`function`	No default value

MultiSelectMenu.Content#

Prop	Type	Default
`css`	`StitchesCss`	No default value
`placement`	`enum`	`"bottom"`
`anchorOffset`	`number`	`4`
`onExitComplete`	`function`	`() => void`

MultiSelectMenu.Clear#

Prop	Type	Default
`as`	`enum`	`button`
`css`	`StitchesCss`	No default value

MultiSelectMenu.Item#

Prop	Type	Default
`as`	`enum`	`div`
`css`	`StitchesCss`	No default value
`value`*	`string`	No default value
`isDisabled`	`boolean`	No default value
`textValue`	`string`	No default value
`endElement`	`React.ReactElement`	No default value

MultiSelectMenu.ItemText#

Prop	Type	Default
`as`	`enum`	`span`

MultiSelectMenu.Group#

Prop	Type	Default
`as`	`enum`	`div`
`css`	`StitchesCss`	No default value

MultiSelectMenu.Label#

Prop	Type	Default
`as`	`enum`	`div`
`css`	`StitchesCss`	No default value

MultiSelectMenu.NestedGroup#

Prop	Type	Default
`as`	`enum`	`div`
`css`	`StitchesCss`	No default value

MultiSelectMenu.NestedGroupLabel#

Prop	Type	Default
`as`	`enum`	`div`
`css`	`StitchesCss`	No default value
`isDisabled`	`boolean`	No default value
`endElement`	`React.ReactElement`	No default value

MultiSelectMenu.Separator#

Prop	Type	Default
`as`	`enum`	`div`
`css`	`StitchesCss`	No default value