A widget that allows the user to select one or more items from a list of choices.
Description
A widget that allows the user to select one or more items from a list of choices. See related combobox and list.
Items within the list are static and, unlike standard HTML select elements, may contain images. List boxes contain children whose role is option.
To be keyboard accessible, authors SHOULD manage focus of descendants for all instances of this role, as described in Managing Focus.
Elements with the role listbox have an implicit aria-orientation value of vertical.
Screen Reader Support For Role=ListBox
| Expectation | JAWS | Narrator | NVDA | Orca | TalkBack | VoiceOver (iOS) | VoiceOver (macOS) | ||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| Chrome | Edge | Firefox | Edge | Chrome | Edge | Firefox | Firefox | Chrome | Safari | Safari | |
| MUST convey its name | supported | supported | supported | supported | supported | supported | supported | supported | supported | none | supported |
| MUST convey its role | supported | supported | supported | none | supported | supported | supported | supported | supported | supported | supported |
| SHOULD convey its boundaries | supported | supported | supported | supported | supported | supported | supported | supported | supported | supported | supported |
Example
HTML Example
<input type="text" aria-label="Tag" role="combobox" aria-expanded="true"aria-autocomplete="list" aria-owns="owned_listbox" aria-activedescendant="selected_option"><ul role=”listbox” id="owned_listbox"><li role="option">Zebra</li><li role="option" id="selected_option">Zoom</li></ul>
HTML Example 2
A page contains a combobox composed of a textbox and a dropdown list of values which the user may choose from. The chosen list item becomes the value of the textbox. As the user navigates through the list via arrow keys, the aria-activedescendant property is adjusted to reflect the id attribute of the current child element which has been navigated to.
<input type="text" aria-activedescendant="cb1-opt6" aria-readonly="true" aria-owns="cb1-list" aria-autocomplete="list" role="combobox" id="cb1-edit"><ul aria-expanded="true" role=”listbox” id="cb1-list"><li role="option" id="cb1-opt1">Alabama</li><li role="option" id="cb1-opt2">Alaska</li><li role="option" id="cb1-opt3">American Samoa</li><li role="option" id="cb1-opt4">Arizona</li><li role="option" id="cb1-opt5">Arkansas</li><li role="option" id="cb1-opt6">California</li><li role="option" id="cb1-opt7">Colorado</li></ul>
Characteristics
Superclass Role
- select
Related Concepts
- list
- HTML select
Required Owned Elements
- option
Supported States and Properties
- aria-multiselectable
- aria-readonly
- aria-required
Inherited States and Properties
- aria-activedescendant
- aria-atomic
- aria-busy (state)
- aria-controls
- aria-current (state)
- aria-describedby
- aria-details
- aria-disabled (state)
- aria-dropeffect
- aria-errormessage
- aria-expanded (state)
- aria-flowto
- aria-grabbed (state)
- aria-haspopup
- aria-hidden (state)
- aria-invalid (state)
- aria-keyshortcuts
- aria-label
- aria-labelledby
- aria-live
- aria-orientation
- aria-owns
- aria-relevant
- aria-roledescription
Name From
- author
Accessible Name Required
- True
Implicit Value for Role
- Default for aria-orientation is vertical.
Semantic HTML
Use the HTML5 <datalist> tag.
<input list="browsers"><datalist id="browsers"><option value="Internet Explorer"><option value="Firefox"><option value="Chrome"><option value="Opera"><option value="Safari"></datalist>
Reference
- W3C (opens new window)
- A11Y Support