Skip to content

Listbox Example with Grouped Options

Listbox Example with Grouped Options

Read This First

The code in this example is not intended for production environments. Before using it for any purpose, read this to understand why.

This is an illustrative example of one way of using ARIA that conforms with the ARIA specification.

About This Example

The following example implementation of the Listbox Pattern demonstrates a single-select listbox widget with grouped options. This widget is functionally similar to an HTML select element with size greater than 1 and options grouped into categories with labeled optgroup elements.

Similar examples include:

Example

Choose your animal sidekick
  • Cat
  • Dog
  • Tiger
  • Reindeer
  • Raccoon
  • Dolphin
  • Flounder
  • Eel
  • Falcon
  • Winged Horse
  • Owl

Accessibility Features

  • Because this listbox implementation is scrollable and manages which option is focused by using aria-activedescendant, the JavaScript must ensure the focused option is visible. So, when a keyboard or pointer event changes the option referenced by aria-activedescendant, if the referenced option is not fully visible, the JavaScript scrolls the listbox to position the option in view.
  • To enhance perceivability when operating the listbox, visual keyboard focus and hover are styled using the CSS :hover and :focus pseudo-classes:
    • To help people with visual impairments identify the listbox as an interactive element, the cursor is changed to a pointer when hovering over the list.
    • To make it easier to distinguish the selected listbox option from other options, selection creates a 2 pixel border above and below the option.

Keyboard Support

The example listbox on this page implements the following keyboard interface. Other variations and options for the keyboard interface are described in the Keyboard Interaction section of the Listbox Pattern.

NOTE: When visual focus is on an option in this listbox implementation, DOM focus remains on the listbox element and the value of aria-activedescendant on the listbox refers to the descendant option that is visually indicated as focused. Where the following descriptions of keyboard commands mention focus, they are referring to the visual focus indicator, not DOM focus. For more information about this focus management technique, see Managing Focus in Composites Using aria-activedescendant.

Key Function
Tab Moves focus into and out of the listbox.
Down Arrow Moves focus to and selects the next option.
Up Arrow Moves focus to and selects the previous option.
Home Moves focus to and selects the first option.
End Moves focus to and selects the last option.
Printable Characters
  • Type a character: focus moves to the next item with a name that starts with the typed character.
  • Type multiple characters in rapid succession: focus moves to the next item with a name that starts with the string of characters typed.

Role, Property, State, and Tabindex Attributes

The example listboxes on this page implement the following ARIA roles, states, and properties. Information about other ways of applying ARIA roles, states, and properties is available in the Roles, States, and Properties section of the Listbox Pattern.

Role Attribute Element Usage
listbox div Identifies the focusable element that has listbox behaviors and contains the listbox options.
aria-labelledby="ID_REF" div Refers to the element containing the listbox label.
tabindex="0" div Includes the listbox in the page tab sequence.
aria-activedescendant="ID_REF" div
  • When an option in the listbox is visually indicated as having keyboard focus, refers to that option.
  • Enables assistive technologies to know which element the application regards as focused while DOM focus remains on the listbox element.
  • When navigation keys, such as Down Arrow, are pressed, the JavaScript changes the value.
  • For more information about this focus management technique, see Managing Focus in Composites Using aria-activedescendant.
group ul Identifies a group of related options
aria-labelledby="ID_REF" ul Refers to the element containing the option group label.
option li Identifies each selectable element containing the name of an option.
aria-selected="true" li
  • Indicates that the option is selected.
  • Applied to the element with role option that is visually styled as selected.
  • The option with this attribute is always the same as the option that is referenced by aria-activedescendant because it is a single-select listbox where selection follows focus.
aria-hidden="true" span Removes the character entity used for the check mark icon from the accessibility tree to prevent it from being included in the accessible name of the option.

JavaScript and CSS Source Code

HTML Source Code

To copy the following HTML code, please open it in CodePen.

Back to Top