Components / Library Version 5.7.0

Nested Select

This component is based on Select and allows grouping the options by categories. Select has a single list of options; Nested Select has several. The dropdown opens with the list of categories, and choosing one reveals a list of options. The component has the same variants as Select for selecting multiple options and searching.

Technical overview

The component accepts wm-optgroup as children, and each wm-optgroup can contain wm-option elements as its children.

PropertiesExamplesAPIAccessibility

* Required property

Properties of wm-nested-select

label *
string
A description for the dropdown. Required even if the label-position is set to none (to ensure assistive technologies can properly describe the component).
all-selected-message
string
For the multiple variant, sets the text to display when all options are selected. Defaults to "All selected".
disabled
boolean
Disables the component.
error-message
string
The message to display if the user input fails a validation performed outside of the component. The component is in error state while this property is set.
label-position
top | left | none
Defaults to top. Set this property to none if no label should be displayed.
max-height
string
Set the dropdown's maximum height. It takes any valid CSS value. Default is 12.5rem.
multiple
boolean
Allows for the selection of multiple options.
placeholder
string
For the multiple variant, sets the placeholder text when no options are selected. Defaults to "Make a selection". To use a placeholder with the single select, see the Notes tab.
required-field
boolean
Renders an asterisk indicating that the field is required.
search-placeholder
string
For the search variant, sets the placeholder text that appears in the search field. Defaults to "Search".
select-all
boolean
Adds a "Select All" button above the options. The button text is "Deselect All" when all options are selected.

Properties of wm-optgroup

disabled
boolean
Disables the group.
label *
string
The group name.

Properties of wm-option

See on the Select component page.

Usage in HTML

Edit the code below to see changes reflected in the example above.

Javascript Sample

Example code for functionality.

Usage in Elm

Code generated from HTML.

wmNestedSelectBlurred

Emitted when the field blurs. Listen to this event to run validation functions. Do not use the standard onBlur event, which will not have the desired behavior.

Emitted by wm-optgroup

wmOptgroupAllSelected

Emitted when the "Select All" button is clicked.

wmOptgroupAllDeselected

Emitted when the "Deselect All" button is clicked.

Emitted by wm-option

wmOptionSelected

Emitted when the option is selected. The event.detail contains a reference to the option which the user clicked.

wmOptionDeselected

Emitted when the option is deselected. The event.detail contains a reference to the option which the user clicked.

Keyboard Support

Button

Key Function
Space Enter Down Arrow
Opens dropdown and focuses the first group.
Up Arrow Opens dropdown and focuses the last group.

Groups list

Key Function
Enter Space Right Arrow Reveals the group's options.
Escape
  • Closes the dropdown.
  • Sets focus to the button.
Up Arrow
  • Moves focus to the previous group.
  • If focus is on the first group, moves focus to the last group.
Down Arrow
  • Moves focus to the next group.
  • If focus is on the last group, moves focus to the first group.
Home Moves focus to the first group.
End Moves focus to the last group.

Options list

Key Function
Space
  • Selects the option. In the multiple variant, toggles the option.
  • Closes the menu and sets focus on the button. In the multiple variant, the menu stays open.
Enter
  • Selects the option. In the multiple variant, toggles the option.
  • Closes the menu.
  • Sets focus on the button.
Escape
  • Closes the dropdown.
  • Sets focus to the button.
Left Arrow Navigate back to the groups list.
Up Arrow
  • Moves focus to the previous option.
  • If focus is on the first option, moves focus to the last option.
Down Arrow
  • Moves focus to the next option.
  • If focus is on the last option, moves focus to the first option.
Home Moves focus to the first option.
End Moves focus to the last option.
A-Z
  • Moves focus to the next option with a label that starts with the typed character if such an option exists.
  • Otherwise, focus does not move.
Back to Top