Listbox

Allows selection of one or more items from a list of options.

Screenshots

No screenshot yet.

Introduction

NOTE: we are in the process of restructuring the Autocomplete, Combobox, Listbox and Select patterns. Please bear with us.

The listbox pattern is a JavaScript widget. It allows selection of one or more items from a list of options.

Because it is not a form control, the value will not be passed to the server. If you require this behaviour, please consider the select pattern instead.

A listbox can be self-contained, or be controlled by another widget (e.g. a textbox in a combobox pattern).

Working Examples

You can take a look at the listbox pattern in action on our examples site.

You can get a quick idea of the required markup structure by viewing our bones project.

Terminology

  • widget: the pattern as a whole, comprised of the parts below

  • listbox: contains a list of options

  • option: each option available for selection

  • checked: state of each option (checked or unchecked)

Configuration

  • autoSelect: a listbox with auto select will update its checked state automatically as a user navigates with arrow keys (similar to a radio button group).

  • multiSelect: a listbox with multiSelect allows more than one option to be selected

  • owner: specify the focusable element that will own and control the listbox programmatically (e.g. a combobox).

Best Practices

This section is not yet available.

Interaction Design

This section provides interaction design for keyboard, screen reader & pointing devices.

Keyboard

If the listbox has no owner, the listbox must be keyboard focusable.

If a listbox has keyboard focus, UP-ARROW and DOWN-ARROW keys must change highlighted option.

For a focusable listbox, keyboard focus will appear to be at two places at the same time (the listbox and the options). In actual fact, keyboard focus always stays on the listbox. The aria-activedescendant property controls the pseudo-focus inside of the listbox and we can use CSS to style the active descendant.

For a listbox with autoSelect configuration, highlighting an option must also select that option (i.e. aria-checked="true").

For a listbox without autoSelect configutation, a highlighted option must be manually selected using the SPACEBAR or ENTER key.

Screen Reader

With virtual cursor on listbox, screen reader should announce role of listbox.

If a listbox has keyboard focus, UP-ARROW and DOWN-ARROW keys must update the active descendant, and that option must be announced.

The checked state of an option must be announced.

Pointer

Clicking or tapping button will toggle expanded state of flyout.

Clicking or tapping option in flyout will update button to that value.

Developer Guide

This section is not yet available.