Open UIOpen UI GitHub

Select (Editor's Draft)

Overview

The <select> is a control that provides a list of options for the user to select from.

Use Cases

The <select> control is primarily leveraged to select an option for within a form. For example when your buying a shirt you may be provided with a <select> that has options for sizes that you then select the appropriate one for you.

Prior Art/Examples

<select> Properties

Attribute NameTypeDefault ValueDescription
autocompletestringoffAllows the developer to provide a hint on how to search the content within the <option>(s)
autofocusboolfalseIf set to true the input will have focus set on page load
disabledboolinherited from containing elementIf set to true the user will not be able to interact with the control
formstringthe form that contains the <select>Represents the form owner, via the form attribute being the same as the id of the <form>
labelsNodeListA NodeList containing the <label> elements associated with the <select> element
lengthint0The number of <option> elements in the <select> element
multipleboolfalseIf set to true this will allow more than one <option>
namestringnullRepresents the name of the control
optionsHTMLOptionsCollectionReturns a HTMLOptionsCollection of the <option> elements contained by the <select> element
requiredboolfalseA value must be provided for the control if set to true
selectedIndexint-1The index of the first or last selected <option> element, depending on the value of multiple
selectedOptionsHTMLCollectionAn HTMLCollection of the selected <option> elements
sizeint0If the <select> is shown with a scrollbar, this represents how many <option>s are visible.
typestring"select-one"Returns either "select-multiple" or "select-one"
validationMessagestring""Represents the message that describes the validation constraints that the control does not satisfy
validityValidityStateRepresents the current validity state of the control
value string""Returns the value property of the first selected <option> if there is one, otherwise an empty string
willValidatebooltrueA boolean that indicates whether the button is a candidate for constraint validation. It is false if any conditions bar it from constraint validation.

<select> Methods

NameDescription
addAdds an <option> to the <select>'s collection of <option> elements
checkValidityChecks whether the element violates any of its validity constraints. If so, fires invalid and returns false
itemReturns the <option> at the specified index in the <select>'s <option> collection
namedItemReturns the <option> in the <select>'s <option> collection with the specified name
removeRemoves the <option> at the specified index in the <select>'s <option> collection
reportValidityIf the <select> violates any of its validity constraints, shows a visual indicator to the user, fires invalid, and returns false
setCustomValiditySets the custom validity message of the <select> to the specified string, or clears any custom validity error if passed an empty string

<optgroup> Properties

Property NameTypeDefault ValueDescription
disabledboolinherited from containing elementIf set to true the user will not be able to interact with any of the <options>(s) in the group
labelstringThe name of the group of <option>s. Required if element is used.

<option> Properties

Property NameTypeDefault ValueDescription
defaultSelectedboolfalseThe initial value of the selected attribute
disabledboolinherited from containing elementIf set to true the user will not be able to interact with the <option>
formHTMLFormElementReturns the form element that the <option> is associated with, the association is inherited from the <select>
indexlongThe position of the <option> in the list of options it belongs to, in tree order
labelstringReflects the value of the value attribute if it exists; else reflects Node.textContent
selected boolfalseIf set to true then the <option> is selected
textstringContains the text content of the element
valuestringReflects the value of the value attribute if it exists; else reflects Node.textContent

Anatomy

Diagram

Currently selected value

Structure

  • <select> - The root element that contains the button and listbox [required]
  • <button> - The button element that contains the selected value and triggers the visibility of the listbox [required]
  • <listbox> - The wrapper that contains the <option>(s) and <optgroup>(s) [required]
  • <optgroup> - Groups <options> together with a label [optional]
  • <option> - Can have one or more and represents the potential values that can be chosen by the user [required]

Content not allowed within the anatomy

The following interactive elements are NOT permitted within a <select> or its children:

  • button (outside of the pre-defined one)
  • datalist
  • input (all types)
  • meter
  • progress
  • select
  • textarea
  • anchor
  • iframe
  • object

Should <a> and <output> be included?

Should this apply to the entire anatomy or solely the <option> and <optgroup> element

Events

select

EventBehaviorImpacts
changeUpdates the textContent property of the selected-value slot with the value property text contenttextContent prop

part button

EventBehaviorImpacts
clickToggles the open state of the <select>open state
clickToggles aria-expanded attributearia-expanded attr
keydown(space)Toggles the open state on the <select>open state
keydown(space)Toggles aria-expandedaria-expanded attr
keydown(enter)Toggles the open state on thopen state
keydown(enter)Toggles aria-expanded on the button partaria-expanded attr

part listbox

EventBehaviorImpacts
keydown(down key)Moves focus to the next <option> in the listboxfocus
keydown(up key)Moves focus to the previous <option> in the listboxfocus
keydown(enter)Changes the selected state of the current <option> and updates the <select> value propertyselected prop
value prop
keydown(space)Changes the selected state of the current <option> and updates the <select> value propertyselected prop
value prop
keydown(enter)If the <select> does not have the multiple attribute then toggle the state of open on the <select>open state
keydown(enter)If the <select> does not have the multiple attribute then toggle the aria-expanded attribute on the button partaria-expanded attr
keydown(space)If the <select> does not have the multiple attribute then toggle the state of open on the <select>open state
keydown(space)If the <select> does not have the multiple attribute then toggle the aria-expanded attribute on the button partaria-expanded attr
keydown(escape)Toggles the open state of the <select>open state

part option

EventBehaviorImpacts
clickChanges the selected state of the current <option> and updates the <select> value propertyselected prop
value prop
clickIf the <select> does not have the multiple attribute then toggle the state of open on the <select>open state
clickIf the <select> does not have the multiple attribute then toggle the aria-expanded attribute on the button partaria-expanded attr

Behavior

States

open

This state is applied to the <select> when the listbox is visible to the user.

required

An <option> from the <select> must be selected when the required attribute is set to true

valid

The <select> meets all its validation constraints, and is therefore considered to be valid.

invalid

The <select> does not meet its validation constraints, and is therefore considered to be invalid.

Interaction & transition of states

Default State

  • Show the currently selected <option> or the first <option>
  • When the user invokes the button by:
    • a pointerup or click event is fired
    • the user presses the space or enter key
  • The state of the <select> is set to open

Open State

  • The currently selected <option>, or the first if one isn't selected, should be visible within the listbox. This may require moving the list to accomodate listbox positioning and available space.
  • The user can dismiss the listbox and remove the state of open from the <select> in any of the following manners:
    • The user clicks outside of the listbox
    • Presses the escape key
    • Selects one, or more (if multiple is true), by clicking or hitting enter or space key

Keyboard traversal

Listbox positioning

When the <select> is in its open state the listbox should

  • Be positioned allow for the greatest visibility of the listbox as possible.
  • Let currentBox equal the button's getBoundingClientRect
  • Let viewportHeight equal document.innerWidth
  • Let availableTop equal viewportHeight - currentBox.top
  • Let availableBottom equal viewportHeight - currentBox.bottom
  • If availableTop is greater than availableBottom:
  • else

Some frameworks allow a forced directionality with the default being an auto positioning as described above.

Use with Assistive Technology

Implements the combobox role per the HTML AAM spec.

Security

Avoiding UI spoofing

If a listbox is rendered outside of the viewport, then it is highly recommended to limit control over the possible adjustments that an author can make. This is due to the developer being able to overlay their content with the application's UI, of which the user trusts and can result in clickjacking due to UI spoofing. If the application enables the author to have complete control over its appearance, the implementor MUST render the listbox within the viewport.

This also MUST apply to embedded content, such as an <iframe> as it may try to mimick the appearance of the site it is being embedded on.

Open Questions

  • Provide arbitrary HTML into <option> elements
    • What is the value of an option with complex content? [Issue 69]
    • How does focus work with focusable children within the control?
    • How does form validation work?

Resources


Acknowledgements

Some method and attribute definitions were sourced from the MDN definitions