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

• W3C (opens new window)
• A11Y Support