Experimental Example of Scrollable Listbox with Actions on Options

Read This First

Experimental content! Do not use except for new standards development purposes. Please read below to understand why.

This is an experimental implementation of potential future techniques that may not yet be supported by web standards.

This example may include ARIA, HTML, CSS, or other code that is not yet included in a final web standard specification.
Experimental content is published in the APG only to facilitate discussion, gather feedback, and support testing of new features in browsers and assistive technologies.
There may be little or no support for this example in any or most browser and assistive technology combinations.
The ARIA and Assistive Technologies Project is developing measurements of assistive technology support for APG examples.

About This Experimental Example

This is an experimental implementation of the draft specification of the aria-actions attribute. The aria-actions property enables an element to reference one or more interactive elements that can be activated to perform an action on the referencing element. In this example, each option element in the listbox references several buttons that perform actions on the option. The relationship provided by aria-actions enables an assistive technology to both communicate the availability of the action button and provide a command for activating the button while focus is on the tab.

The following example implementation of the Listbox Pattern demonstrates a scrollable single-select listbox widget. This widget is functionally similar to an HTML select input where the size attribute has a value greater than one.

This example also demonstrates how to provide buttons that provide contextual actions for each item in the list. Each option has an associated set of four actions that enable users to move an option up or down, favorite it, or remove it from the list. The contextual actions are provided by buttons that appear on hover or focus. The buttons are referenced by aria-actions specified on the option element, which enables them to be discovered and activated by an assistive technology user while focus is on the option.

Similar examples include:

Scrollable Listbox Example: Single-select listbox that scrolls to reveal more options, similar to HTML select with size attribute greater than one.
Example Listboxes with Rearrangeable Options: Examples of both single-select and multi-select listboxes with accompanying toolbars where options can be added, moved, and removed.
Listbox Example with Grouped Options: Single-select listbox with grouped options, similar to an HTML select with optgroup children.

Example

Choose your favorite transuranic element (actinide or transactinide).

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.
`Right Arrow`	If an option has focus, moves focus to the first action button. If an action button has focus, moves focus to the next action button for the current option. If the last action button has focus, does nothing.
`Left Arrow`	If any action button except for the first action button has focus, moves focus to the previous action button for the current option. If the first action button has focus, moves focus to the current option. If an option has focus, does nothing.
`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 listbox on this page implements 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`		`ul`	Identifies the focusable element that has listbox behaviors and contains the listbox options.
	`aria-labelledby="ID_REF"`	`ul`	Refers to the element containing the listbox label.
	`tabindex="0"`	`ul`	Includes the listbox in the page tab sequence.
	`aria-activedescendant="ID_REF"`	`ul`	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.
`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-actions=""`	`li`	Indicates to assistive technologies that the option will have actions available on focus or hover, enabling the assistive technology to focus the element to gain access to the actions. Applied to all elements with role option when they are not visually styled as selected and are not referenced by `aria-activedescendant`.
	`aria-actions="ID_REFS"`	`li`	Specifies the ID attributes of the action buttons that are associated with the option. Applied to the element with role option that is visually styled as selected and is referenced by `aria-activedescendant`.
	`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

CSS: listbox.css
JavaScript: listbox.js, listbox-scrollable.js

HTML Source Code

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


<p>
  Choose your favorite transuranic element (actinide or transactinide).
</p>
<div class="listbox-area">
  <div>
    <span id="ss_elem" class="listbox-label">
      Transuranium elements:
    </span>
    <ul id="ss_elem_list"
        tabindex="0"
        role="listbox"
        aria-labelledby="ss_elem">
      <li id="ss_elem_None" role="option">
        <span class="checkmark" aria-hidden="true"></span>
        None
      </li>
      <li id="ss_elem_Np" role="option">
        <span class="checkmark" aria-hidden="true"></span>
        Neptunium
      </li>
      <li id="ss_elem_Pu" role="option">
        <span class="checkmark" aria-hidden="true"></span>
        Plutonium
      </li>
      <li id="ss_elem_Am" role="option">
        <span class="checkmark" aria-hidden="true"></span>
        Americium
      </li>
      <li id="ss_elem_Cm" role="option">
        <span class="checkmark" aria-hidden="true"></span>
        Curium
      </li>
      <li id="ss_elem_Bk" role="option">
        <span class="checkmark" aria-hidden="true"></span>
        Berkelium
      </li>
      <li id="ss_elem_Cf" role="option">
        <span class="checkmark" aria-hidden="true"></span>
        Californium
      </li>
      <li id="ss_elem_Es" role="option">
        <span class="checkmark" aria-hidden="true"></span>
        Einsteinium
      </li>
      <li id="ss_elem_Fm" role="option">
        <span class="checkmark" aria-hidden="true"></span>
        Fermium
      </li>
      <li id="ss_elem_Md" role="option">
        <span class="checkmark" aria-hidden="true"></span>
        Mendelevium
      </li>
      <li id="ss_elem_No" role="option">
        <span class="checkmark" aria-hidden="true"></span>
        Nobelium
      </li>
      <li id="ss_elem_Lr" role="option">
        <span class="checkmark" aria-hidden="true"></span>
        Lawrencium
      </li>
      <li id="ss_elem_Rf" role="option">
        <span class="checkmark" aria-hidden="true"></span>
        Rutherfordium
      </li>
      <li id="ss_elem_Db" role="option">
        <span class="checkmark" aria-hidden="true"></span>
        Dubnium
      </li>
      <li id="ss_elem_Sg" role="option">
        <span class="checkmark" aria-hidden="true"></span>
        Seaborgium
      </li>
      <li id="ss_elem_Bh" role="option">
        <span class="checkmark" aria-hidden="true"></span>
        Bohrium
      </li>
      <li id="ss_elem_Hs" role="option">
        <span class="checkmark" aria-hidden="true"></span>
        Hassium
      </li>
      <li id="ss_elem_Mt" role="option">
        <span class="checkmark" aria-hidden="true"></span>
        Meitnerium
      </li>
      <li id="ss_elem_Ds" role="option">
        <span class="checkmark" aria-hidden="true"></span>
        Darmstadtium
      </li>
      <li id="ss_elem_Rg" role="option">
        <span class="checkmark" aria-hidden="true"></span>
        Roentgenium
      </li>
      <li id="ss_elem_Cn" role="option">
        <span class="checkmark" aria-hidden="true"></span>
        Copernicium
      </li>
      <li id="ss_elem_Nh" role="option">
        <span class="checkmark" aria-hidden="true"></span>
        Nihonium
      </li>
      <li id="ss_elem_Fl" role="option">
        <span class="checkmark" aria-hidden="true"></span>
        Flerovium
      </li>
      <li id="ss_elem_Mc" role="option">
        <span class="checkmark" aria-hidden="true"></span>
        Moscovium
      </li>
      <li id="ss_elem_Lv" role="option">
        <span class="checkmark" aria-hidden="true"></span>
        Livermorium
      </li>
      <li id="ss_elem_Ts" role="option">
        <span class="checkmark" aria-hidden="true"></span>
        Tennessine
      </li>
      <li id="ss_elem_Og" role="option">
        <span class="checkmark" aria-hidden="true"></span>
        Oganesson
      </li>
    </ul>
  </div>
</div>