Scrollable Listbox Example
- -About This Example
-
- 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.
-
Similar examples include:
--
-
- 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
selectwithoptgroupchildren.
-
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
:hoverand:focuspseudo-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 | -
-
|
-
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 |
-
-
|
-
option |
- - | li |
- Identifies each selectable element containing the name of an option. | -
| - | aria-selected="true" |
- li |
-
-
|
-
| - | 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.
- -
-
-
-