Components / Library Version 5.4.0

Select

This component provides a dropdown list of options, similar to the HTML select element. It displays the selected option(s) when the dropdown is closed.

Several variants are available. Single Select (the default), multiselect, which has an optional "Select All" button, and a search field to filter the options (which can be used with both single and multiselect).

NB: If you want to implement a dropdown where activating an item triggers an action, please see the Action Menu's selector variant.

Technical overview

The component should be used exclusively with the wm-option component, which represent the options.

To use the component, listen to the wmOptionSelected and wmOptionDeselected events. The event.detail contains a reference to the option the user clicked, which can then be used to change the option's selected state. See the Javascript sample and Api tab for more information.

PropertiesExamplesAPIAccessibilityNotes

* Required property

Properties of the parent element wm-select

label *
string
A description for the dropdown. Required even if the label-position is set to none (for accessibility reasons).
all-selected-message
string
For the multiple variant, sets the text to display when all options are selected and some are overflowing. 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
Overwrites the default max-height value for the options list. 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 the children elements wm-option

disabled
boolean
Disables the option.
selected
boolean
Sets the option's selected state. Anything other than the bool False or the string "false" selects the option.
subinfo
string
This text will be displayed on the right side and italicized. See second option in the example.

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.
wmSelectBlurred
Emitted when the field blurs. Listen for this event to run validation functions. Do not use the standard onBlur event, which will not have the desired behavior.
wmSelectAllSelected
Emitted when the "Select All" button is clicked.
wmSelectAllDeselected
Emitted when the "Deselect All" button is clicked.

Properties of the children 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 Opens dropdown and focuses the selected option. If no option is selected, the first option is selected by default.
Down Arrow Opens dropdown and focuses option one down from the last option selected.
Up Arrow Opens dropdown and focuses option one up from the first option selected.

Dropdown Listbox

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.
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.

Usage & API

  • The Select with Search variants are intended to be used with 50 or fewer options. Any more present usability and potential performance issues. Designs that call for a Select with Search with more than 50 options should consider an alternate pattern.

Single Select's "placeholder"

Single Select doesn't have a placeholder, and must always have a selected option. Most of the time this UX pattern requires a "special" first option, otherwise we have no way to know whether the user selected the first option or didn't make a selection at all. You may use the first option as a null value to resolve this issue. In this case, for accessibility and consistency reasons, the language should be limited to one of the following:

  • None
  • Select an option
  • --
Back to Top