Edit page


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.


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

  1. filled
  2. outline
  3. flat


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


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


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


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:


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.


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.


Prop nameTypeDefaultRequiredDescription

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


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


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.


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