Listbox Button

A button that expands to reveal a listbox in a flyout.

Screenshots

Introduction

The listbox button pattern is a JavaScript widget. It is a button that expands to reveal a listbox in a flyout.

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

Do not call a listbox button a "dropdown"! The term "dropdown" is ambiguous and could be confused with a menu button, combobox, select or any other kind of overlay that "drops down".

Updated: March 15th, 2021 (labelling)

Working Examples

Experience the pattern in action on our companion eBay MIND Patterns examples website.

Examine the required markup structure in our Bones GitHub project.

View a fully styled example in our eBay Skin CSS framework.

Terminology

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

button: the button that opens the flyout

flyout: the overlay that contains the listbox

listbox: the list of options

option: an option, with state

label: internal and/or external text element(s)

Configuration

See related listbox pattern.

Best Practices

A listbox button's accessible label must at all times reflect its function.

Care is needed when labelling a listbox button! A listbox button attempts to mimic the behaviour of an HTML select by displaying the currently selected value in its collapsed state. In HTML however, a button is labelled by its inner text, whereas a select is labelled by an external label tag.

All of this leaves us with a conundrum, with three potential solutions outlined below.

Additionally Labelled Listbox Button

We can use aria-labelledby to stitch together an external text element with the internal value.

<span id="el1">Colour</span><button aria-labelledby="el1 el2"><span id="el2">blue</span></button>

Internally Labelled Listbox Button

The button's inner text can be written as a key/value pair, where key denotes purpose and value represents the current selection.

<button>Colour: blue<button>

Explicitly Labelled Listbox Values

We can write our option values such that the context can be derived from the option value text alone (this isn't always easy or recommended).

<div role="option">Colour blue</div>

Interaction Design

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

Please also see related listbox pattern for best practices of nested listbox.

Keyboard

With focus on button, pressing SPACEBAR will will toggle expanded state of button.

With focus on listbox, pressing ESCAPE key will collapse button.

Screen Reader

With virtual cursor on button, screen reader should announce role, label (see "Best Practices" section above), value & state..

Pointer

Clicking or tapping button will toggle expanded state of flyout.

Clicking or tapping an option in flyout will update button value and collapse the flyout.

Developer Guide

This section is not yet available.