(Deprecated) Collapsible Dropdown Listbox Example
- -About This Example
-Deprecation Warning
-- This pattern has been deprecated, and will be removed in a future version of the ARIA Authoring Practices. - The select-only combobox should be used as an alternative to this pattern. -
-
- The following example implementation of the Listbox Pattern demonstrates a collapsible single-select listbox widget that is functionally similar to an HTML select input with the attribute size="1".
- The widget consists of a button that triggers the display of a listbox.
- In its default state, the widget is collapsed (the listbox is not visible) and the button label shows the currently selected option from the listbox.
- When the button is activated, the listbox is displayed and the current option is focused and selected.
-
Similar examples include:
--
-
- Select-Only Combobox: A single-select combobox with no text input that is functionally similar to an HTML
selectelement.
- - Scrollable Listbox Example: Single-select listbox that scrolls to reveal more options, similar to HTML
selectwithsizeattribute 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
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 | -
-
|
-
| Enter | -
-
|
-
| Escape | -If the listbox is displayed, collapses the listbox and moves focus to the button. | -
| Down Arrow | -
-
|
-
| Up Arrow | -
-
|
-
| Home | -If the listbox is displayed, moves focus to and selects the first option. | -
| End | -If the listbox is displayed, 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 | -
|---|---|---|---|
| - | aria-labelledby="ID_REF1 ID_REF2" |
- button |
-
-
|
-
| - | aria-haspopup="listbox" |
- button |
- Indicates that activating the button displays a listbox. | -
| - | aria-expanded="true" |
- button |
-
-
|
-
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="-1" |
- ul |
-
-
|
-
| - | aria-activedescendant="ID_REF" |
- ul |
-
-
|
-
option |
- - | li |
- Identifies each selectable element containing the name of an option. | -
| - | aria-selected="true" |
- li |
-
-
|
-
JavaScript and CSS Source Code
--
-
- - CSS: - listbox.css - -
- - JavaScript: - listbox.js, listbox-collapsible.js - -
HTML Source Code
-To copy the following HTML code, please open it in CodePen.
- -
-
-
-