<iframe src="https://www.googletagmanager.com/ns.html?id=GTM-5HGSQD2L" height="0" width="0" style="display:none;visibility:hidden" title="GTM"></iframe>

Buttonbar

A set of closely related controls or actions, where selecting one applies it immediately.

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.

The preview has been updated.

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

The preview has been updated.

To set a default state:

  • In the React API, use defaultSelectedValue on the Buttonbar to specify an initial state.
  • In the Vanilla API, put a checked property 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.

The preview has been updated.

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.

The preview has been updated.

To set a default state:

  • In the React API, use defaultSelectedValues on the Buttonbar to specify an initial state.
  • In the Vanilla API, put a checked property 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.

The preview has been updated.

Toolbar

Use toolbar when you want to display a series of secondary Buttons.

The preview has been updated.

Disabled

Use disabled on ButtonbarButton when its option is unavailable.

The preview has been updated.

Implementation

  • A <fieldset> tag cannot be used because styling of that tag is not supported enough in Chrome.

Accessibility

  • Include an aria-label whose 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-controls attribute whose value is the id of the section it controls.

Props

Buttonbar
This component is implemented using the <div /> as the root element. You can utilize the native attributes supported by <div /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.
See core props for additional props that can be applied to this component.
proptyperequireddescriptiondefault
variant"toolbar" | "single-select" | "multi-select" | nullfalse
- `single-select` means using radio buttons, which are mutually exclusive - `multi-select` means using checkbox options, of which many can be selected at once - `toolbar` means using regular buttons
single-select
width"standard" | "full-width" | nullfalse
The width of the buttonbar
standard
namestring | nullfalse
Name for the input element(ButtonbarButton)
null
selectedValueButtonbarSelectedValuefalse
'value' of currently selected button. Used when controlling the state of the component
null
defaultSelectedValueButtonbarSelectedValuefalse
The default selected value of the buttonbar. Used when not controlling the state of the component
null
onSelectedValueChange((value: ButtonbarSelectedValue, event: ChangeEvent<HTMLInputElement>) => void) | nullfalse
Callback fired when selected option is changed. `event` is the input's onChange event
null
selectedValuesButtonbarSelectedValues | nullfalse
List of 'values' of currently selected buttons.
null
defaultSelectedValuesButtonbarSelectedValues | nullfalse
By default selected buttons.
null
onSelectedValuesChange((selectedValues: ButtonbarSelectedValues, event: ChangeEvent<HTMLInputElement>) => void) | nullfalse
Callback fired when one of the selections' value changes. It is passed the updated list of `selectedValues` and the actual `<input>` event in case you need it.
null
ButtonbarButton
This component is implemented using the <input /> as the root element. You can utilize the native attributes supported by <input /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.
See core props for additional props that can be applied to this component.
proptyperequireddescriptiondefault
valuestringtrue
The value of the button
null
ButtonbarButtonLabel
This component is implemented using the <label /> as the root element. You can utilize the native attributes supported by <label /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.
See core props for additional props that can be applied to this component.

Related