Skip to content

Button Group

The Button Group combines a set of related buttons.


The Button Group component combines a set of buttons that have similar or related functionality.

  <Button />
  <IconButton />



The Button Group component can wrap Button and IconButton.

Press Enter to start editing



The Button Group component supports Joy UI's four global variants: outlined (default), solid, soft, and plain.

The variant prop is passed to the buttons, not the Button Group itself.


The Button Group component comes in three sizes: sm, md (default), and lg.

Press Enter to start editing


Every palette included in the theme is available via the color prop. Play around combining different colors with different variants.


Use the disabled prop to disable all the buttons. Note that if you explicitly specify the disabled prop on the buttons directly, it will override what is used in the Button Group.

Press Enter to start editing


Use spacing prop to control the gap between buttons. If the spacing is set to 0 (by default), the radius of the buttons will be adjusted to form a continuous surface.

Press Enter to start editing

Vertical group

The Button Group component can be displayed vertically using the orientation="vertical" prop. Note that this prop has no effect on IconButton component.

Stretching button

Use the buttonFlex prop to make the buttons fill the available space of the Button Group component.

Minimum width

For a large container, control the default width of the buttons by providing a valid CSS flex value to the buttonFlex prop.


Lorem Ipsum is simply dummy text of the printing and typesetting industry.

Split button

The Button Group component can also be used to create a split button. The dropdown can change the button action (as in this example) or be used to immediately trigger a related action.

Separator color

When the Button Group's variant is not outlined, separators are created between buttons. To control the color of the separator, override the CSS variable --ButtonGroup-separatorColor via the sx prop.

hsl(0 100% 50%)

Using it with a Tooltip

The Button Group component supports arbitrary children that wrap the buttons by preserving the same appearance.

Press Enter to start editing

Common examples

Pill button group

Use the CSS variable --ButtonGroup-radius to control the radius of the start and end buttons.

Press Enter to start editing

Custom separator

This example uses the Divider component to create a custom separator between the buttons. The CSS variable --ButtonGroup-separatorColor is then set with an arbitrary value to remove the default separator.


See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.