Playground
Single-Select
In a single-select Buttonbar, the Buttonbar acts as a set of radio buttons. Only one value may be selected at a time. In React Visage, this is the default behavior.
<Buttonbar variant="single-select" defaultSelectedValue="B"><ButtonbarButton value="A"><ButtonbarButtonLabel>Radio 1</ButtonbarButtonLabel></ButtonbarButton><ButtonbarButton value="B"><ButtonbarButtonLabel>Radio 2</ButtonbarButtonLabel></ButtonbarButton></Buttonbar>
<div class="buttonbar" role="toolbar" aria-label="My Example Label"><!-- aria-label value must be localized --><inputtype="radio"name="exampleRadioName"value="A"id="exampleButtonbarRadio1"/><label for="exampleButtonbarRadio1">Radio 1</label><inputtype="radio"name="exampleRadioName"value="B"id="exampleButtonbarRadio2"checked="checked"/><label for="exampleButtonbarRadio2">Radio 2</label></div>
To set a default state:
In vanilla JS, put a
checkedproperty onto the radio button that should be selected by default.In React, use
defaultSelectedValueon theButtonbarto specify an initial state. If you want to fully control the state (beyond just the initial state), check out the Managing State section.
Multi-Select
This behavior allows multiple options to be selected at the same time, as if the buttonbar were a series of checkboxes.
<Buttonbar variant="multi-select" defaultSelectedValues={['A', 'C']}><ButtonbarButton value="A"><ButtonbarButtonLabel>Check 1</ButtonbarButtonLabel></ButtonbarButton><ButtonbarButton value="B"><ButtonbarButtonLabel>Check 2</ButtonbarButtonLabel></ButtonbarButton><ButtonbarButton value="C"><ButtonbarButtonLabel>Check 3</ButtonbarButtonLabel></ButtonbarButton></Buttonbar>
<div class="buttonbar" role="toolbar" aria-label="My Example Label"><!-- aria-label value must be localized --><inputtype="checkbox"name="exampleButtonbarCheckbox1"id="exampleButtonbarCheckbox-1"checked="checked"/><label for="exampleButtonbarCheckbox-1">Check 1</label><inputtype="checkbox"name="exampleButtonbarCheckbox2"id="exampleButtonbarCheckbox-2"/><label for="exampleButtonbarCheckbox-2">Check 2</label><inputtype="checkbox"name="exampleButtonbarCheckbox3"id="exampleButtonbarCheckbox-3"checked="checked"/><label for="exampleButtonbarCheckbox-3">Check 3</label></div>
To set a default state:
In React, use
defaultSelectedValueson theButtonbarto specify an initial state. If you want to fully control the state (beyond just the initial state), check out the Managing State section.In vanilla JS, put a
checkedproperty onto any checkbox that should be checked by default.
Secondary Textbuttons
A buttonbar can also consist of a series of secondary Textbuttons:
<Buttonbar><TextButton value={'1'} skin="secondary">Textbutton 1</TextButton><TextButton value={'2'} skin="secondary">Textbutton 2</TextButton><TextButton value={'3'} skin="secondary">Textbutton 3</TextButton><TextButton value={'4'} skin="secondary" disabled>Textbutton Disabled</TextButton></Buttonbar>
<div class="buttonbar" role="toolbar"><button class="textbutton textbutton-skin-secondary" value="1">Textbutton 1</button><button class="textbutton textbutton-skin-secondary" value="2">Textbutton 2</button><button class="textbutton textbutton-skin-secondary" value="3">Textutton 3</button><button class="textbutton textbutton-skin-secondary" value="4" disabled="">Textbutton Disabled</button></div>
Width
Any type of Buttonbar can be made full-width, so it will fill all available width.
In react-visage, set the widthVariant property to "full-width".
<Buttonbarvariant="single-select"defaultSelectedValue="B"widthVariant="full-width"><ButtonbarButton value="A"><ButtonbarButtonLabel>Radio 1</ButtonbarButtonLabel></ButtonbarButton><ButtonbarButton value="B"><ButtonbarButtonLabel>Radio 2</ButtonbarButtonLabel></ButtonbarButton><ButtonbarButton value="C"><ButtonbarButtonLabel>Radio 3</ButtonbarButtonLabel></ButtonbarButton><ButtonbarButton value="D" disabled><ButtonbarButtonLabel>Radio disabled</ButtonbarButtonLabel></ButtonbarButton></Buttonbar>
<Buttonbar widthVariant="full-width">etc.</Buttonbar>
<div class="buttonbar buttonbar-full-width" role="toolbar">etc</div>
Managing State in React
If you want to control the state of the React Buttonbar component, you can make use of the selectedValue/selectedValues and onSelectedValueChange/onSelectedValuesChange props.
Single Select
single-select Buttonbar should use the selectedValue and onSelectedValueChange props in order to control the state.
onSelectedValueChange will be invoked with the new value as the first arg and the actual <input> event as the second arg in case you need it.
() => {const [selectedValue, setSelectedValue] = React.useState('B')return (<Buttonbarvariant="single-select"selectedValue={selectedValue}onSelectedValueChange={(newSelectedValue, event) =>setSelectedValue(newSelectedValue)}><ButtonbarButton value="A"><ButtonbarButtonLabel>Radio 1</ButtonbarButtonLabel></ButtonbarButton><ButtonbarButton value="B"><ButtonbarButtonLabel>Radio 2</ButtonbarButtonLabel></ButtonbarButton><ButtonbarButton value="C"><ButtonbarButtonLabel>Radio 3</ButtonbarButtonLabel></ButtonbarButton><ButtonbarButton value="D" disabled><ButtonbarButtonLabel>Radio disabled</ButtonbarButtonLabel></ButtonbarButton></Buttonbar>)}
Multi Select
multi-select Buttonbars should use the selectedValues and onSelectedValuesChange props in order to control the state.
selectedValues is an array of selected values.
onSelectedValuesChange will be invoked with an updated array of selected values as the first arg and the actual <input> event as the second arg in case you need it.
() => {const [selectedValues, setSelectedValues] = React.useState(['B', 'C'])return (<Buttonbarvariant="multi-select"selectedValues={selectedValues}onSelectedValuesChange={(newSelectedValues, event) =>setSelectedValues(newSelectedValues)}><ButtonbarButton value="A"><ButtonbarButtonLabel>Check 1</ButtonbarButtonLabel></ButtonbarButton><ButtonbarButton value="B"><ButtonbarButtonLabel>Check 2</ButtonbarButtonLabel></ButtonbarButton><ButtonbarButton value="C"><ButtonbarButtonLabel>Check 3</ButtonbarButtonLabel></ButtonbarButton><ButtonbarButton value="D" disabled><ButtonbarButtonLabel>Check disabled</ButtonbarButtonLabel></ButtonbarButton></Buttonbar>)}
Components
Buttonbar
| Prop | Type | Default | Description |
|---|---|---|---|
| widthVariant | "standard" | "full-width" | "standard" | The width of the buttonbar |
| variant | "single-select" | "multi-select" | 'single-select' |
|
| selectedValue | string | 'value' of currently selected button. Used by | |
| defaultSelectedValue | string | By default selected button. Used by | |
| onSelectedValueChange | (value: string, event: ChangeEvent<HTMLInputElement>) => void | Callback fired when selected option is changed, Used by | |
| selectedValues | ButtonbarSelectedValues | List of 'values' of currently selected buttons. Used by | |
| defaultSelectedValues | ButtonbarSelectedValues | By default selected buttons. Used by | |
| onSelectedValuesChange | (selectedValues: ButtonbarSelectedValues, event: ChangeEvent<HTMLInputElement>) => void | Callback fired when one of the selections' value changes. It is passed the updated list of Used by |
All other props are forwarded to the element specified in thecomponentprop(default: <div/>)
ButtonbarButton
ButtonbarButton has no props of its own
All props are forwarded to the element specified in thecomponentprop(default: <input/>)
ButtonbarButtonLabel has no props of its own
Guidelines
Designer Guidelines
Buttonbars of radio buttons can be used as a toggle control when the choices are not "on" or "off". (If you need to toggle between "on" and "off" states, consider a instead.)
Buttonbars should not be used for navigation.
Developer Guidelines
You cannot use a
<fieldset>tag for the buttonbar, because Chrome doesn't support enough styling of that tag.
Accessibility Guidelines
The buttonbar needs 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, it should have an
aria-controlsattribute whose value is the id of the section it controls.