Button Group

The Button Group combines a set of related buttons.

Introduction

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

<ButtonGroup>
  <Button />
  ...
  <IconButton />
</ButtonGroup>

Basics

The Button Group component can wrap Button and IconButton.

<ButtonGroup aria-label="outlined primary button group">
  <Button>One</Button>
  <Button>Two</Button>
  <Button>Three</Button>
  <IconButton>
    <Settings />
  </IconButton>
</ButtonGroup>

<ButtonGroup aria-label="outlined primary button group">
  <Button>One</Button>
  <Button>Two</Button>
  <Button>Three</Button>
  <IconButton>
    <Settings />
  </IconButton>
</ButtonGroup>

Press Enter to start editing

Customization

Variants

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.

Sizes

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

<ButtonGroup size="sm" aria-label="outlined button group">
  <Button>One</Button>
  <Button>Two</Button>
  <Button>Three</Button>
</ButtonGroup>
<ButtonGroup aria-label="plain button group">
  <Button>One</Button>
  <Button>Two</Button>
  <Button>Three</Button>
</ButtonGroup>
<ButtonGroup size="lg" aria-label="soft button group">
  <Button>One</Button>
  <Button>Two</Button>
  <Button>Three</Button>
</ButtonGroup>

<ButtonGroup size="sm" aria-label="outlined button group">
  <Button>One</Button>
  <Button>Two</Button>
  <Button>Three</Button>
</ButtonGroup>
<ButtonGroup aria-label="plain button group">
  <Button>One</Button>
  <Button>Two</Button>
  <Button>Three</Button>
</ButtonGroup>
<ButtonGroup size="lg" aria-label="soft button group">
  <Button>One</Button>
  <Button>Two</Button>
  <Button>Three</Button>
</ButtonGroup>

Press Enter to start editing

Colors

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

Disabled

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.

<ButtonGroup disabled aria-label="disabled button group">
  <Button>One</Button>
  <Button>Two</Button>
  <Button>Three</Button>
  <IconButton disabled={false}>
    <Settings />
  </IconButton>
</ButtonGroup>

<ButtonGroup disabled aria-label="disabled button group">
  <Button>One</Button>
  <Button>Two</Button>
  <Button>Three</Button>
  <IconButton disabled={false}>
    <Settings />
  </IconButton>
</ButtonGroup>

Press Enter to start editing

Spacing

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.

<ButtonGroup spacing="0.5rem" aria-label="spacing button group">
  <Button>One</Button>
  <Button disabled>Two</Button>
  <Button>Three</Button>
  <IconButton>
    <Settings />
  </IconButton>
</ButtonGroup>

<ButtonGroup spacing="0.5rem" aria-label="spacing button group">
  <Button>One</Button>
  <Button disabled>Two</Button>
  <Button>Three</Button>
  <IconButton>
    <Settings />
  </IconButton>
</ButtonGroup>

Press Enter to start editing

The type of value can be:

string: any valid CSS length unit, for example px, rem, em, etc.
number: will be calculated by theme.spacing function.
array: the responsive values based on the breakpoints defined in the theme.
object: the key must be one of the breakpoints defined in the theme (the defaults are "xs" | "sm" | "md" | "lg" | "xl"), and the value is the spacing of type string or number.

<ButtonGroup spacing={{ xs: 0, sm: 1, md: '2rem' }}>...</ButtonGroup>

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.

Title

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%)

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

<ButtonGroup variant="soft" aria-label="tooltip button group">
  <Tooltip arrow title="Go to profile">
    <Button startDecorator={<Person />}>Hover me</Button>
  </Tooltip>
  <Tooltip arrow title="Open settings">
    <span>
      <IconButton disabled>
        <Settings />
      </IconButton>
    </span>
  </Tooltip>
  <Tooltip arrow title="Go to profile">
    <Button endDecorator={<Person />}>Hover me</Button>
  </Tooltip>
</ButtonGroup>

<ButtonGroup variant="soft" aria-label="tooltip button group">
  <Tooltip arrow title="Go to profile">
    <Button startDecorator={<Person />}>Hover me</Button>
  </Tooltip>
  <Tooltip arrow title="Open settings">
    <span>
      <IconButton disabled>
        <Settings />
      </IconButton>
    </span>
  </Tooltip>
  <Tooltip arrow title="Go to profile">
    <Button endDecorator={<Person />}>Hover me</Button>
  </Tooltip>
</ButtonGroup>

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.

<ButtonGroup
  aria-label="radius button group"
  sx={{ '--ButtonGroup-radius': '40px' }}
>
  <Button>One</Button>
  <Button>Two</Button>
  <Button>Three</Button>
  <IconButton>
    <Settings />
  </IconButton>
</ButtonGroup>

<ButtonGroup
  aria-label="radius button group"
  sx={{ '--ButtonGroup-radius': '40px' }}
>
  <Button>One</Button>
  <Button>Two</Button>
  <Button>Three</Button>
  <IconButton>
    <Settings />
  </IconButton>
</ButtonGroup>

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.

API

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

Button Group

Introduction

Playground

Basics

Customization

Variants

Sizes

Colors

Disabled

Spacing

Vertical group

Stretching button

Minimum width

Split button

Separator color

Using it with a Tooltip

Common examples

Pill button group

Custom separator

API