Components / Library version 3.3.1

Select

This component provides a dropdown list of options, similar to the HTML select element. By default only a single selection can be made, but a multiple variant is supported.

When closed, it displays the selected option. The first option is selected by default. It should have at least one option component as a child.

NB: If you want to implement a dropdown where selecting an item doesn't change the text displayed when the dropdown is closed, please see the Action Menu component (with action-menu-type="selector").

Properties Examples Events Accessibility Notes

* Required property

** Required in certain cases

label *
string
A description for the dropdown. Required even if the label-position is set to none (for accessibility reasons).
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.
required-field
boolean
Renders an asterisk indicating that the field is required.
invalid
boolean
Changes the input border color to red.
error-message
string
The message to display if the user input fails a validation performed outside of the component.
disabled
boolean
Disables the component.
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".
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".

For the properties of the children, see option.

Usage in HTML

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

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. Replaces the deprecated wmComponentBlurred.

Keyboard Support

Button

Key Function
SpaceEnter 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-Za-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.
  • This component has no minimum width. This might be necessary, in particular to ensure that the subinfo text doesn't overlap the option text.
  • This component has no maximum width. It will take the width of its parent by default.
  • To trigger an action when an option is selected, attach a function to the onClick attribute of the wm-option. (This is accessible: the component emits a click when the user selects an option with the Enter key).
  • The version with an input (search field) is not implemented at this point.
  • Depending on context, screen readers may not announce the expanded state. This is normal behavior and does not constitutes an accessibility issue.

In a compound component like Select or Action Menu, child components are rendered in the parent's slot element, part of its shadow DOM tree. Slots essentially serve as a placeholder for markup that you the developer define in the light DOM tree, like <wm-menuitem>, <wm-option>, text content, or other child elements.

The browser distributes the child elements defined in the light DOM into the shadow DOM of the parent. The result is a flattened DOM tree—a merger of the the light DOM and the shadow DOM. This flattened tree is what you see in DevTools and what is rendered on the page.

With the standard implementation of the component, dynamically updating the child items will throw an error. Elm's efficient diffing of the DOM will register that only the child items have changed and try to update them, but the component has already been composed.

Rendering the component in a Keyed node and giving it a dynamic id will cause the entire component, rather than just the child items, to render anew, avoiding the error.