diff --git a/aria-practices.html b/aria-practices.html index 19f63ef405..6f112e42f0 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -1583,10 +1583,13 @@

Listbox

Examples

-

Listbox Examples: Two examples of the listbox pattern demonstrating differences between single-select and multi-select implementation as well as the use of action buttons with key shortcuts for arranging items in a list.

+
-
+

Keyboard Interaction

For a vertically oriented listbox:

@@ -441,11 +418,6 @@

Example 2: Multi-Select Listbox

-

Example 3: Scrollable Listbox

- -
- -
diff --git a/examples/listbox/listbox-scrollable.html b/examples/listbox/listbox-scrollable.html new file mode 100644 index 0000000000..f292110cdf --- /dev/null +++ b/examples/listbox/listbox-scrollable.html @@ -0,0 +1,236 @@ + + + + +Scrollable Listbox Example | WAI-ARIA Authoring Practices 1.1 + + + + + + + + + + + + + + +
+

Scrollable Listbox Example

+

+ Please provide feedback on this example in + issue 469. +

+

+ The following example implementation of the + design pattern for listbox + 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

+ +
+

Choose your favorite transuranic element (actinide or transactinide).

+
+
+ Transuranium elements: +
    +
  • Neptunium
    • +
  • Plutonium
    • +
  • Americium
    • +
  • Curium
    • +
  • Berkelium
    • +
  • Californium
    • +
  • Einsteinium
    • +
  • Fermium
    • +
  • Mendelevium
    • +
  • Nobelium
    • +
  • Lawrencium
    • +
  • Rutherfordium
    • +
  • Dubnium
    • +
  • Seaborgium
    • +
  • Bohrium
    • +
  • Hassium
    • +
  • Meitnerium
    • +
  • Darmstadtium
    • +
  • Roentgenium
    • +
  • Copernicium
    • +
  • Nihonium
    • +
  • Flerovium
    • +
  • Moscovium
    • +
  • Livermorium
    • +
  • Tennessine
    • +
  • Oganesson
    • +
+
+
+
+ +

Notes

+

This listbox is scrollable; it has more options than its height can accommodate.

+
    +
  1. + Scrolling only works as expected if the listbox is the options' offsetParent. + The example uses position: relative on the listbox to that effect. +
    2. +
  2. When an option is focused that isn't (fully) visible, the listbox's scroll position is updated: +
      +
    1. If Up Arrow or Down Arrow is pressed, the previous or next option is scrolled into view.
      2. +
    2. If Home or End is pressed, the listbox scrolls all the way to the top or to the bottom.
      3. +
    3. 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.
      4. +
    4. If the mouse is clicked on a partially visible option, it will be scrolled fully into view.
      5. +
    +
    3. +
  3. When a fully visible option is focused in any way, no scrolling occurs.
    4. +
  4. 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.
    5. +
+
+ +
+

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. +

+ + + + + + + + + + + + + + + + + + + + + + + + + +
KeyFunction
Down Arrow +
    +
  • Moves focus to and selects the next option.
    • +
+
Up ArrowMoves focus to and selects the previous option.
HomeMoves focus to and selects the first option.
EndMoves 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. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
RoleAttributeElementUsage
listboxulIdentifies the focusable element that has listbox behaviors and contains the listbox options.
aria-labelledby="ID_REF"ulRefers to the element containing the listbox label.
tabindex="0"ulIncludes the listbox in the page tab sequence.
aria-activedescendant="ID_REF"ul +
    +
  • Tells assistive technologies which of the options, if any, is visually indicated as having keyboard focus.
    • +
  • DOM focus remains on the ul element and the idref specified for aria-activedescendant refers to the li element that is visually styled as focused.
    • +
  • When navigation keys, such as Down Arrow, are pressed, the JavaScript changes the value.
    • +
+
role="option"liIdentifies 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.
    • +
+
+
+ +
+

Javascript and CSS Source Code

+ +
+ +
+

HTML Source Code

+ +
+ + + +
+
+ + +