Listbox Button Component

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

The listbox button pattern is a JavaScript widget. It is a button that expands to reveal a [listbox](listbox) in a [popover](../disclosure/popover). 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](select) pattern instead. **Avoid calling 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".

A listbox button is intended for use as a custom implementation of the native HTML select element's single -select use case.

Because a button element does not store form data, its value will not be submitted along with other form data without the assistance of JavaScript.

Terminology

We use the following terminology when discussing this pattern.

  • widget : the pattern as a whole, comprised of the parts below
  • button : the button that opens the flyout
  • popover : the overlay element that contains the listbox
  • listbox : the list of options
  • option : an option, with state
  • label : internal and/or external text element(s)
List ComponentListbox Component