Select Menu

Select Menu is a contextual overlay that displays a searchable options menu for the user to pick from.

The goal of SelectMenu is to provide building blocks to create experience interchangeable with the native Select component, while being highly customizable and offering extended capabilities such as multiple selection.

SelectMenu is a base component used by Single Select Menu and Multi Select Menu. You should prefer to use these abstractions unless you have very specific requirements and need more granular control.

Import#

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

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

SelectMenu.Root: The wrapper that contains all the parts of a select menu and provides context for its children.
SelectMenu.Trigger: The trigger that toggles the select menu.
SelectMenu.Value: A wrapper for the selected value(s).
SelectMenu.Icon: The default chevron icon used as an open/close indicator.
SelectMenu.Clear: The button that clears the selected value(s).
SelectMenu.Content: A wrapper for the content to be rendered when the select menu is open. It positions itself by aligning over SelectMenu.Trigger.
SelectMenu.Item: A container for select menu's item of choice.
SelectMenu.ItemText: A wrapper around textual part of SelectMenu.Item.
SelectMenu.ItemIndicator: A wrapper to put a visual indicator into, such as Checkbox or icon that is displayed when the item(s) are selected.
SelectMenu.Group: A wrapper for a group of select menu items.
SelectMenu.Label: The component that renders an accessible label of SelectMenu.Group.
SelectMenu.Separator: The component that renders a horizontal divider between menu items and groups.
SelectMenu.HiddenSelect: The hidden <select> HTML element used for integration with HTML forms.

Examples#

Basic#

Controlled#

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

You can use the placeholder prop on SelectMenu.Value for when the select menu has no value.

Be sure to add aria-label to SelectMenu.Trigger as users won't see the placeholder when an item becomes selected.

With indicators#

With complex item content#

SelectMenu.Value will display the selected item SelectMenu.ItemText's content.

If only text content is provided as children to SelectMenu.Item, it will get wrapped with SelectMenu.ItemText automatically. However, when you're dealing with more complex content of an item, you need to use SelectMenu.ItemText explicitly.

With groups#

When dealing with a larger amount of options, groups help to keep them organized.

HTML Form support#

SelectMenu.HiddenSelect with a name property can be used for integration with HTML forms.

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#

SelectMenu.Root#

Prop	Type	Default
`value`	`string \| string[]`	No default value
`defaultValue`	`string \| 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`
`multi`	`boolean`	`false`
`isDisabled`	`boolean`	`false`
`isRequired`	`boolean`	No default value
`validationStatus`	`enum`	No default value

SelectMenu.Trigger#

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

SelectMenu.Content#

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

SelectMenu.Value#

Prop	Type	Default
`as`	`enum`	`span`
`css`	`StitchesCss`	No default value
`placeholder`	`React.ReactNode`	No default value
`children`	`enum`	No default value

SelectMenu.Icon#

Prop	Type	Default
`css`	`StitchesCss`	No default value

SelectMenu.Clear#

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

SelectMenu.Item#

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

SelectMenu.ItemText#

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

SelectMenu.ItemIndicator#

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

SelectMenu.Group#

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

SelectMenu.Label#

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

SelectMenu.Separator#

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

SelectMenu.HiddenSelect#

Prop	Type	Default
`forceMount`	`boolean`	`false`