ButtonGroup

⚠️ This documentation file needs to be reviewed ⚠️, but the component is ready to use.

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>

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.

• In most use cases, secondary action color is probably the best option for buttons in a group as it works good with the colors of the selected state.

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

• In the background, ButtonGroup uses the fieldset element. Not only it improves the accessibility of the group, it also allows you to make use of its built-in features like disabling all nested inputs or pairing the group with a form outside. Consult the MDN docs to learn more.

• Be careful with using startCorner and endCorner options for grouped buttons. Overflowing elements may cause undesired interaction problems.

Shared Properties

You can set the following properties directly on ButtonGroup to be shared for all buttons inside the group:

• size,
• 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 (in theory) technically possible, from the design point of view it's undesirable to group buttons of totally different types or sizes.

Sizes

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

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

Block button groups span the full width of a parent:

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

States

Disabled State

Disables all buttons inside the group.

<ButtonGroup disabled>
  <Button color="secondary" label="Week" />
  <Button color="secondary" label="Month" />
  <Button color="secondary" label="Year" />
</ButtonGroup>

Feedback State

When user's action triggers an asynchronous process on background, feedback state of individual buttons can be indicated by showing an icon.

<ButtonGroup>
  <Button
    color="success"
    label="Week"
    feedbackIcon={<Icon icon="ok-circle" />}
  />
  <Button color="secondary"label="Month" />
  <Button color="secondary"label="Year" />
</ButtonGroup>

Selected State

To highlight the selected option, just apply the selected color variant for the desired item.

<ButtonGroup>
  <Button color="selected" label="Week" />
  <Button color="secondary" label="Month" />
  <Button color="secondary" 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.

<span id="period-label">Period:</span>
<ButtonGroup aria-labelledby="period-label">
  <Button color="selected" label="Week" aria-pressed />
  <Button color="secondary" label="Month" aria-pressed={false} />
  <Button color="secondary" label="Year" aria-pressed={false} />
</ButtonGroup>

Forwarding HTML Attributes

In addition to the options below in the component's API section, you can specify React synthetic events or any HTML attribute you like. All attributes that don't interfere with the API are forwarded to the root <fieldset> HTML element. This enables making the component interactive and helps to improve its accessibility.

👉 Refer to the MDN reference for the full list of supported attributes of the fieldset element.

API

Theming

Custom Property	Description
--rui-ButtonGroup__inner-border-radius	Inner border radius of buttons
--rui-ButtonGroup--filled__gap	Gap between filled buttons
--rui-ButtonGroup--filled__separator__width	Separator width for filled buttons
--rui-ButtonGroup--filled__separator__color	Separator color for filled buttons