Single Select Menu

Input control allowing for choosing single option from searchable options menu.

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

It is interchangable with the native Select component, but prettier and more powerful.

Import#

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

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

SingleSelectMenu: The wrapper that contains all the parts of a select menu and provides context for its children.
SingleSelectMenu.Trigger: The button that toggles the select menu.
SingleSelectMenu.Content: A wrapper for the content to be rendered when the select menu is open. It positions itself by aligning over SingleSelectMenu.Trigger.
SingleSelectMenu.Clear: The button that clears the value of select menu.
SingleSelectMenu.Item: A container for select menu's item of choice.
SingleSelectMenu.ItemText: A wrapper around textual part of SingleSelectMenu.Item.
SingleSelectMenu.ItemIndicator: A visual cue in form of an icon that is displayed when the item is selected.
SingleSelectMenu.Group: A wrapper for the group of select menu items.
SingleSelectMenu.Label: The component that renders an accessible label of SingleSelectMenu.Group.
SingleSelectMenu.Separator: The component that renders a horizontal divider between menu items and groups.

Examples#

Basic#

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

SingleSelectMenu 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 SingleSelectMenu in "uncontrolled" mode, you can specify the default selected option with defaultValue property.

Controlled#

You can easily make the SingleSelectMenu 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 SingleSelectMenu.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.

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 SingleSelectMenu 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 SingleSelectMenu with the FormField.Label.

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

Sizes#

SingleSelectMenu 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#

SingleSelectMenu.Trigger and SingleSelectMenu.Item can be decorated with supporting icons or elements using startElement and endElement props.

Active indicators#

When item inside the Single Select Menu is selected its text content is highligted in bold. For additional emphasis you may include SingleSelectMenu.ItemIndicator to add a visual indicator rendered when the item is selected.

Custom render value#

By default, SingleSelectMenu.Trigger will automatically display the selected item text content.

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

Groups#

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

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

HTML Form integration#

SingleSelectMenu 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.
Browser autofill integration via a hidden native <select> element.

API Reference#

SingleSelectMenu#

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
`autoComplete`	`string`	No default value

SingleSelectMenu.Trigger#

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

SingleSelectMenu.Content#

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

SingleSelectMenu.Clear#

Prop	Type	Default
`css`	`StitchesCss`	No default value
`label`*	`string`	No default value

SingleSelectMenu.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
`startElement`	`React.ReactElement`	No default value
`endElement`	`React.ReactElement`	No default value

SingleSelectMenu.ItemText#

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

SingleSelectMenu.ItemIndicator#

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

SingleSelectMenu.Group#

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

SingleSelectMenu.Label#

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

SingleSelectMenu.Separator#

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