Listbox Example with Grouped Options
The following example implementation of the design pattern for listbox 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:
- Scrollable Listbox Example: Single-select listbox that scrolls to reveal more options, similar to HTML
select
withsize
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.
- Collapsible Dropdown Listbox Example: Single-select collapsible listbox that expands when activated, similar to HTML
select
with the attributesize="1"
.
Example
- Land
- Cat
- Dog
- Tiger
- Reindeer
- Raccoon
- Water
- Dolphin
- Flounder
- Eel
- Air
- Falcon
- Winged Horse
- Owl
Notes
This listbox is scrollable; it has more options than its height can accommodate.
-
Scrolling only works as expected if the listbox is the options'
offsetParent
. The example usesposition: relative
on the listbox to that effect. - When an option is focused that isn't (fully) visible, the listbox's scroll position is updated:
- If Up Arrow or Down Arrow is pressed, the previous or next option is scrolled into view.
- If Home or End is pressed, the listbox scrolls all the way to the top or to the bottom.
- If
focusItem
is called, the focused option will be scrolled to the top of the view if it was located above it or to the bottom if it was below it. - If the mouse is clicked on a partially visible option, it will be scrolled fully into view.
- When a fully visible option is focused in any way, no scrolling occurs.
-
Normal scrolling through any scrolling mechanism (including Page Up and Page Down) works as expected.
The scroll position will jump as described for
focusItem
if a means other than a mouse click is used to change focus after scrolling.
Keyboard Support
The example listboxes on this page implement the following keyboard interface. Other variations and options for the keyboard interface are described in the Keyboard Interaction section of the Listbox Design Pattern.
Key | Function |
---|---|
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. |
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 Design 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 |
|
|
role="group" |
ul |
Identifies a group of related options | |
aria-labelledby="ID_REF" |
ul |
Refers to the element containing the option group label. | |
role="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
- Javascript: listbox-scrollable.js
HTML Source Code