Open UIOpen UI GitHub

Select (Working Draft)

The <select> element is a control that allows the user to select from a set of potential options.

Anatomy

Diagram

Default = <button>${value}<span part="icon-arrow"></span></button>Default = <option></option>

Part Definitions

::host — Root element that contains the button and the pop-up.

::part-button — An interactive element that toggles the appearance of the pop-up. This element has a tab stop.

::part-pop-up — An interactive element containing the set of options the user can select from.

Events

  • ::host Listening for toggle-pop-up event to hide/show ::part-pop-up

  • ::part-button Listens to click event and dispatches toggle-pop-up event

  • ::part-button Listening for option-change event to update selected value shown

  • ::part-pop-up Listening for option-change event to dispatch toggle-pop-up event

  • ::part-button Dispatches custom event split-button-clicked

Accessibility

Keyboard

Keyboard users can operate the <select> as follows:

  • Focus on the <select> element using the Tab key (there is a tab stop on part-button). The control can be focused by default by setting the autofocus attribute.
  • Having focus, but with the pop-up still closed, users can:
    • Change the selection to the next option using the Down arrow
    • Change the selection to the previous option using the Up arrow
    • Change the selection to the first option starting with a certain sequence by typing that sequence
    • Cycle the selection through options starting with a certain letter by continually typing that letter
  • Having focus, the user can open the popup using the Enter key or the Space key. The popup can be dismissed using the Enter key or the Esc key.
  • Having focus and with the pop-up open, the user can select options in the same manner as above. As the user traverses the options, the currently-selected option is always visible and highlighted, with the menu scrolling as necessary.
  • Upon selection, the select control's value field is updated to the respective option's value accordingly.

Assistive Technology

Implements the combobox role per the HTML AAM spec.

Forced Colors

Placeholder for now, dependent on standardization on parts definitions.

States / Properties

<select>

  • open (bool): Controls whether the dropdown is open.

  • defaultOpen (bool): The initial value for open. Defaults to false.

  • value (string): The currently selected option.

  • multiple (bool): Controls whether the user should be able to select multiple items. Defaults to false.

  • searchable (bool): Controls whether the list of options can be searched. If true, a search field is added to the element, and the list of options is filtered by value (matching on prefix, case insensitive) unless overridden by onSearch. Defaults to false.

  • onSearch (function): Callback function fired when the search input changes (searchable must be enabled).

  • onSelect (function): Callback function fired when the selected option changes.

  • popupDirection (enum: auto | above | below): Specify the direction the options list should pop up towards. "Auto" is the behavior of <select> today (pop up in the direction with the most screen real estate).

  • repeatScroll (bool): Specify whether, while using arrow keys, the menu should scroll back to the first option after reaching the last option.

  • autofocus (bool): Get focus by default.

  • autocomplete (string): Provides a hint for the user agent's autocomplete feature.

  • disabled (bool): Prevents the user from interacting with the control. Defaults to false.

  • form (string): Associates the element with a form in the document whose id is this value.

  • name (string): Specify the name of the control for purposes of form submission.

  • required (bool): Indicates that an option with a non-empty string value must be selected.

  • size (number): If the control is displayed inset (e.g. in multiple mode), specify the number of options that should be visible.

<option>

  • disabled (bool): Prevents the user from selecting this option. Defaults to false.

  • selected (bool): Indicates that this option is initially selected (overrides the default of the first option being initially selected).

  • label (string): Label indicating the meaning of the option.

  • value (string): The option's associated value (e.g. to be submitted with a form).

<optgroup>

  • disabled (bool): Prevents the user from selecting any options in this option group. Defaults to false.

  • label (string): Label for the group of options.

Resources

Investigation of Custom Select Control Patterns

Blog Post on Built-in Form Controls With Survey Data

MDN Reference on Current <Select>

WHATWG Living Standard on <Select>