Edit page

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:

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.

  • 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, 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. filled
  2. outline
  3. flat

Filled

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

Outline

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

Flat

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

Sizes

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

Block button groups span the full width of a parent:

States

Disabled State

Disables all buttons inside the group.

Feedback State

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

Active State

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

Accessibility

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

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 <div> 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 div element.

API

Prop nameTypeDefaultRequiredDescription
blockboolfalsefalse

If true, the button group will span the full width of its parent.

childrennodenullfalse

Buttons to be grouped. If none are provided nothing is rendered.

disabledboolfalsefalse

If true, all buttons inside the group will be disabled.

priority'filled' │ 'outline' │ 'flat''filled'false

Visual priority to highlight or suppress the buttons.

size'small' │ 'medium' │ 'large''medium'false

Size of the buttons.

Theming

Custom PropertyDescription
--rui-ButtonGroup--filled__gapGap between filled buttons
--rui-ButtonGroup--filled__separator__widthSeparator width for filled buttons
--rui-ButtonGroup--filled__separator__colorSeparator color for filled buttons
--rui-ButtonGroup--flat__gapGap between flat buttons
--rui-ButtonGroup--flat__separator__widthSeparator width for flat buttons
--rui-ButtonGroup--flat__separator__colorSeparator color for flat buttons
--rui-ButtonGroup--outline__gapGap between outline buttons