<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 actions visually grouped together.

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.

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
namestring | nullfalse
Name for the input element(ButtonbarButton)
null
width"standard" | "full-width" | nullfalse
The width of the buttonbar
standard
selectedValuestring | nullfalse
'value' of currently selected button. Used by `single-select` variant.
null
defaultSelectedValuestring | nullfalse
By default selected button. Used by `single-select` variant.
null
onSelectedValueChange((value: ButtonbarSelectedValue, event: ChangeEvent<HTMLInputElement>) => void) | nullfalse
Callback fired when selected option is changed, `event` is actual `<input>` event in case you need it. Used by `single-select` variant.
null
variant"toolbar" | "single-select" | "multi-select" | nullfalse
`single-select` means using radio buttons `multi-select` means using checkbox options `toolbar` means using regular buttons
null
selectedValuesstring[] | nullfalse
List of 'values' of currently selected buttons. Used by `multi-select` variant.
null
defaultSelectedValuesstring[] | nullfalse
By default selected buttons. Used by `multi-select` variant.
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. Used by `multi-select` variant.
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

Was this page useful?

Thanks for your feedback!

Feel free to include your name if you wish to have a follow up conversation.


Single-SelectMulti-SelectToolbar
Published: Jan 31, 2022Last updated: Sep 18, 2024