• Down Arrow: Moves focus to the next option.
• Up Arrow: Moves focus to the previous option.
• Home (Optional): Moves focus to first option. Supporting this key is strongly recommended for lists with more than five options.
• End (Optional): Moves focus to last option. Supporting this key is strongly recommended for lists with more than five options.
• Space: Toggle option selection.

Listbox

References:

• Listbox Authoring Practice Guide
• listbox role spec
• Focus vs Selection and the Perception of Dual Focus
• Managing Focus in Composites Using aria-activedescendant

Interactions

• #2

  • If none of the options are selected before the listbox receives focus, the first option receives focus. Optionally, the first option may be automatically selected.
  • If an option is selected before the listbox receives focus, focus is set on the selected option.

• #4

  • If none of the options are selected before the listbox receives focus, focus is set on the first option and there is no automatic change in the selection state.
  • If one or more options are selected before the listbox receives focus, focus is set on the first option in the list that is selected

• #7

  • Down Arrow: Moves focus to the next option. Optionally, in a single-select listbox, selection may also move with focus.
  • Up Arrow: Moves focus to the previous option. Optionally, in a single-select listbox, selection may also move with focus.
  • Home: Moves focus to first option. Optionally, in a single-select listbox, selection may also move with focus. Supporting this key is strongly recommended for lists with more than five options.
  • End: Moves focus to last option. Optionally, in a single-select listbox, selection may also move with focus. Supporting this key is strongly recommended for lists with more than five options.
  • Space: changes the selection state of the focused option.

• Type-ahead is recommended for all listboxes, especially those with more than seven options:

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

Multiple Selection

We'll be implementing the recommended approach, which doesn't require holding modifier keys.

• #9
  • Shift + Down Arrow (Optional): Moves focus to and toggles the selected state of the next option.
  • Shift + Up Arrow (Optional): Moves focus to and toggles the selected state of the previous option.
  • Shift + Space (Optional): Selects contiguous items from the most recently selected item to the focused item.
  • Control + Shift + Home (Optional): Selects the focused option and all options up to the first option. Optionally, moves focus to the first option.
  • Control + Shift + End (Optional): Selects the focused option and all options down to the last option. Optionally, moves focus to the last option.
  • Control + A (Optional): Selects all options in the list. Optionally, if all options are selected, it may also unselect all options.

Horizontal Orientation

• Down Arrow performs as Right Arrow is described above, and vice versa.
• Up Arrow performs as Left Arrow is described above, and vice versa.

Selection follow focus

TODO: Deciding When to Make Selection Automatically Follow Focus

Separate Controls

• Select/Unselect All

WAI-ARIA Roles, States, and Properties

• An element that contains or owns all the listbox options has role listbox. closed #2
• Each option in the listbox has role option and is contained in or owned by either:
  • The element with role listbox. closed #2
  • An element with role group that is contained in or owned by the element with role listbox.
• Options contained in a group are referred to as grouped options and form what is called an option group. If a listbox contains grouped options, then:
  • All option groups contain at least one option.
  • Each option group has an accessible name provided via aria-label or aria-labelledby.
• If the element with role listbox is not part of another widget, such as a combobox, then it has either a visible label referenced by aria-labelledby or a value specified for aria-label.
• If the listbox supports selection of more than one option, the element with role listbox has aria-multiselectable set to true. Otherwise, aria-multiselectable is either set to false or the default value of false is implied.
• The selection state of each selectable option is indicated with either aria-selected or aria-checked:
  • If the selection state is indicated with aria-selected, then aria-checked is not specified for any options. Alternatively, if the selection state is indicated with aria-checked, then aria-selected is not specified for any options. See notes below regarding considerations for which property to use and for details of the unusual conditions that might allow for both properties in the same listbox.
  • If any options are selected, each selected option has either aria-selected or aria-checked set to true. No more than one option is selected at a time if the element with role listbox does not have aria-multiselectable set to true.
  • All options that are selectable but not selected have either aria-selected or aria-checked set to false.
  • Note that except in listboxes where selection follows focus, the selected state is distinct from focus. For more details, see this description of differences between focus and selection and Deciding When to Make Selection Automatically Follow Focus.
• If the complete set of available options is not present in the DOM due to dynamic loading as the user scrolls, their aria-setsize and aria-posinset attributes are set appropriately.
• If options are arranged horizontally, the element with role listbox has aria-orientation set to horizontal. The default value of aria-orientation for listbox is vertical.

• Shift + Down Arrow (Optional): Moves focus to and toggles the selected state of the next option.
• Shift + Up Arrow (Optional): Moves focus to and toggles the selected state of the previous option.
• Shift + Space (Optional): Selects contiguous items from the most recently selected item to the focused item.
• Control + Shift + Home (Optional): Selects the focused option and all options up to the first option. Optionally, moves focus to the first option.
• Control + Shift + End (Optional): Selects the focused option and all options down to the last option. Optionally, moves focus to the last option.
• Control + A (Optional): Selects all options in the list. Optionally, if all options are selected, it may also unselect all options.

When a multi-select listbox receives focus:

• If none of the options are selected before the listbox receives focus:
  • focus is set on the first option, and there is no automatic change in the selection state.
• If one or more options are selected before the listbox receives focus:
  • focus is set on the first option in the list that is selected

Focus should be managed like Managing Focus in Composites Using aria-activedescendant, since roving tabindex, wouldn't work when using a combobox (which requires focus to be on the text input element)

• If none of the options are selected before the listbox receives focus, the first option receives focus.
  • Optionally, the first option may be automatically selected we decided to not implement this on the mvp
• If an option is selected before the listbox receives focus, focus is set on the selected option.
• If an option is selected, the selected option receives focus