WAI-ARIA: Role=Listbox

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 |
Role=Listbox 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
- WAI-ARIA 1.2 Specification
Refer to the notes from the WAI-ARIA 1.2 specification for more information on role=listbox. - A11Y Support
The screenreader compatibility for each of the ARIA attributes is taken from the A11Y Support. Please refer to the original source if screenreader compatibility is updated for role=listbox.