React UI
Edit page
Home
Getting Started
Customize
Foundation
Components: UI
Alert Badge Button ButtonGroup
Basic Usage General Guidelines Priorities Sizes States Accessibility API Card CheckboxField Modal Radio ScrollView SelectField Table TextArea TextField Toggle
Components: Layouts
CSS Helpers
Readme

# ButtonGroup

ButtonGroup visually groups related buttons together.

##
Basic Usage

To implement the ButtonGroup component, you need to import it first:

    import { ButtonGroup } from '@react-ui-org/react-ui';

And use it:

<ButtonGroup> <Button label="Week" /> <Button label="Month" /> <Button label="Year" /> </ButtonGroup>

    <ButtonGroup>  <Button label="Week" />  <Button label="Month" />  <Button label="Year" /></ButtonGroup>

See
API for all available options.

## General Guidelines

- Use button group to group
  related actions that a user can take. Buttons should not be grouped just to save space on the screen.

- Use short labels or icons so the buttons can fit small screens.

- For toggling between on/off states, use rather the Toggle component.

- For switching between options in a form that needs to be submitted, use rather the SelectField or Radio components.

### Shared Properties

You can set the following properties directly on ButtonGroup to be shared for all buttons inside the group: size, priority, disabled state, and block width. These properties are then passed over to individual buttons. At the same time, they cannot be overridden on the buttons' level. While technically possible, from the design point of view it's undesirable to group buttons of totally different types or sizes.

## Priorities

There are three visual priorities of buttons which exactly copy the priorities of the Button component:

1. default
2. outline
3. flat

### Default

The default, high-emphasis priority should be used for primary actions of your app.

<ButtonGroup> <Button label="Week" /> <Button label="Month" /> <Button label="Year" /> </ButtonGroup>

    <ButtonGroup>  <Button label="Week" />  <Button label="Month" />  <Button label="Year" /></ButtonGroup>

### Outline

Medium-emphasis buttons to contain actions that are important but not primary in your app.

<ButtonGroup priority="outline"> <Button label="Week" /> <Button label="Month" /> <Button label="Year" /> </ButtonGroup>

    <ButtonGroup priority="outline">  <Button label="Week" />  <Button label="Month" />  <Button label="Year" /></ButtonGroup>

### Flat

Flat buttons are designed for less pronounced actions to help maintain focus on the content.

<ButtonGroup priority="flat"> <Button label="Week" /> <Button label="Month" /> <Button label="Year" /> </ButtonGroup>

    <ButtonGroup priority="flat">  <Button label="Week" />  <Button label="Month" />  <Button label="Year" /></ButtonGroup>

## Sizes

All existing button sizes are also available on the button group level: small, medium, and large.

<ButtonGroup size="small"> <Button label="Week" /> <Button label="Month" /> <Button label="Year" /> </ButtonGroup> <ButtonGroup> <Button label="Week" /> <Button label="Month" /> <Button label="Year" /> </ButtonGroup> <ButtonGroup size="large"> <Button label="Week" /> <Button label="Month" /> <Button label="Year" /> </ButtonGroup>

    <ButtonGroup size="small">  <Button label="Week" />  <Button label="Month" />  <Button label="Year" /></ButtonGroup><ButtonGroup>  <Button label="Week" />  <Button label="Month" />  <Button label="Year" /></ButtonGroup><ButtonGroup size="large">  <Button label="Week" />  <Button label="Month" />  <Button label="Year" /></ButtonGroup>

Block button groups span the full width of a parent:

<ButtonGroup block> <Button label="Week" /> <Button label="Month" /> <Button label="Year" /> </ButtonGroup>

    <ButtonGroup block>  <Button label="Week" />  <Button label="Month" />  <Button label="Year" /></ButtonGroup>

## States

### Disabled State

Disables all buttons inside the group.

<ButtonGroup disabled> <Button label="Week" /> <Button label="Month" /> <Button label="Year" /> </ButtonGroup> <ButtonGroup priority="outline" disabled> <Button label="Week" /> <Button label="Month" /> <Button label="Year" /> </ButtonGroup> <ButtonGroup priority="flat" disabled> <Button label="Week" /> <Button label="Month" /> <Button label="Year" /> </ButtonGroup>

    <ButtonGroup disabled>  <Button label="Week" />  <Button label="Month" />  <Button label="Year" /></ButtonGroup><ButtonGroup priority="outline" disabled>  <Button label="Week" />  <Button label="Month" />  <Button label="Year" /></ButtonGroup><ButtonGroup priority="flat" disabled>  <Button label="Week" />  <Button label="Month" />  <Button label="Year" /></ButtonGroup>

### Active State

To highlight the selected option, the active state can be achieved by setting a different button variant for the active item.

<ButtonGroup> <Button variant="dark" label="Week" /> <Button label="Month" /> <Button label="Year" /> </ButtonGroup> <ButtonGroup priority="outline"> <Button variant="dark" label="Week" /> <Button label="Month" /> <Button label="Year" /> </ButtonGroup> <ButtonGroup priority="flat"> <Button variant="dark" label="Week" /> <Button label="Month" /> <Button label="Year" /> </ButtonGroup>

    <ButtonGroup>  <Button variant="dark" label="Week" />  <Button label="Month" />  <Button label="Year" /></ButtonGroup><ButtonGroup priority="outline">  <Button variant="dark" label="Week" />  <Button label="Month" />  <Button label="Year" /></ButtonGroup><ButtonGroup priority="flat">  <Button variant="dark" label="Week" />  <Button label="Month" />  <Button label="Year" /></ButtonGroup>

## Accessibility

You can improve the accessibility of your ButtonGroup by linking it to a label and communicating the state of individual options.

Period:
<> <span id="period-label">Period:</span> <ButtonGroup aria-labelledby="#period-label"> <Button label="Week" aria-pressed variant="dark" /> <Button label="Month" aria-pressed={false} /> <Button label="Year" aria-pressed={false} /> </ButtonGroup> </>

    <>  <span id="period-label">Period:</span>  <ButtonGroup aria-labelledby="#period-label">    <Button label="Week" aria-pressed variant="dark" />    <Button label="Month" aria-pressed={false} />    <Button label="Year" aria-pressed={false} />  </ButtonGroup></>

## API

block
bool
false
children
Array<element>
required
disabled
bool
false
priority
'default' │ 'outline' │ 'flat'
'default'
size
'small' │ 'medium' │ 'large'
'medium'

Next: Card →