Use Buttonbar...
- To pick one choice from a linear set of closely related choices (such as “Front” and “Back”) and immediately apply that selection.
- To select between 2-5 choices.
- As a toggle control when the choices are not “on” or “off”.
Don't use Buttonbar...
- As a form of navigation.
- To select more than 6+ choices, as this can be difficult to parse and take up too much horizontal space. Use a Dropdown or Listbox instead.
- As a toggle control when the choices are “on” or “off”. Use a Toggle Switch instead.
Width
Use width="full-width" to grow a Buttonbar to fill its container.
ShareSingle-Select
Use single-select when you want only one value to be selected at a time. The Buttonbar will act as a set of radio buttons.
To set a default state:
- In the React API, use
defaultSelectedValueon theButtonbarto specify an initial state. - In the Vanilla API, put a
checkedproperty onto the radio button that should be selected by default.
To control the state of the React API Buttonbar component, use the selectedValue and onSelectedValueChange props. onSelectedValueChange will be invoked with the new value as the first argument and the actual <input> event as the second argument in case you need it.
Multi-Select
Use multi-select when you want to allow multiple options to be selected at the same time. The Buttonbar will act as a series of checkboxes.
To set a default state:
- In the React API, use
defaultSelectedValueson theButtonbarto specify an initial state. - In the Vanilla API, put a
checkedproperty onto the radio button that should be selected by default.
To control the state of the React API Buttonbar component, use the selectedValues and onSelectedValuesChange props. selectedValues is an array of selected values. onSelectedValuesChange will be invoked with an updated array of selected values as the first argument and the actual <input> event as the second argument in case you need it.
Toolbar
Use toolbar when you want to display a series of secondary Buttons.
Implementation
- A
<fieldset>tag cannot be used because styling of that tag is not supported enough in Chrome.
Accessibility
- Include an
aria-labelwhose value is a localized description of what the buttonbar is or does, e.g. "Change view". - If the Buttonbar controls another section of the page, include an
aria-controlsattribute whose value is the id of the section it controls.