Skip to main content

Button Group

Available from version 0.2.0

The Button Group combines a set of related buttons.

Basics​

import { ButtonGroup } from 'tailwind-joy/components';

The Button Group component can wrap Button and IconButton.

import { MdSettings } from 'react-icons/md';
import { Button, ButtonGroup, IconButton } from 'tailwind-joy/components';
import { iconClass } from 'tailwind-joy/utils';

export function ButtonGroupBasics() {
  return (
    <ButtonGroup>
      <Button>One</Button>
      <Button>Two</Button>
      <Button>Three</Button>
      <IconButton>
        <MdSettings className={iconClass()} />
      </IconButton>
    </ButtonGroup>
  );
}
info

iconClass() is an adapter function provided by Tailwind-Joy.

Customization​

Variants​

The Button Group component supports four variants: solid, soft, outlined (default), and plain.

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

import { Box, Button, ButtonGroup } from 'tailwind-joy/components';

export function ButtonGroupVariants() {
  return (
    <Box className="flex flex-col items-center justify-center gap-4">
      <ButtonGroup variant="solid">
        <Button>One</Button>
        <Button>Two</Button>
        <Button>Three</Button>
      </ButtonGroup>
      <ButtonGroup variant="soft">
        <Button>One</Button>
        <Button>Two</Button>
        <Button>Three</Button>
      </ButtonGroup>
      <ButtonGroup variant="outlined">
        <Button>One</Button>
        <Button>Two</Button>
        <Button>Three</Button>
      </ButtonGroup>
      <ButtonGroup variant="plain">
        <Button>One</Button>
        <Button>Two</Button>
        <Button>Three</Button>
      </ButtonGroup>
    </Box>
  );
}

Sizes​

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

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

import { Box, Button, ButtonGroup } from 'tailwind-joy/components';

export function ButtonGroupSizes() {
  return (
    <Box className="flex flex-col items-center justify-center gap-4">
      <ButtonGroup size="sm">
        <Button>One</Button>
        <Button>Two</Button>
        <Button>Three</Button>
      </ButtonGroup>
      <ButtonGroup size="md">
        <Button>One</Button>
        <Button>Two</Button>
        <Button>Three</Button>
      </ButtonGroup>
      <ButtonGroup size="lg">
        <Button>One</Button>
        <Button>Two</Button>
        <Button>Three</Button>
      </ButtonGroup>
    </Box>
  );
}

Colors​

The Button Group component supports five colors: primary, neutral (default), danger, success, and warning.

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

import { Box, Button, ButtonGroup } from 'tailwind-joy/components';

export function ButtonGroupColors() {
  return (
    <Box className="flex flex-col items-center justify-center gap-4">
      <ButtonGroup color="primary">
        <Button>One</Button>
        <Button>Two</Button>
        <Button>Three</Button>
      </ButtonGroup>
      <ButtonGroup color="neutral">
        <Button>One</Button>
        <Button>Two</Button>
        <Button>Three</Button>
      </ButtonGroup>
      <ButtonGroup color="danger">
        <Button>One</Button>
        <Button>Two</Button>
        <Button>Three</Button>
      </ButtonGroup>
      <ButtonGroup color="success">
        <Button>One</Button>
        <Button>Two</Button>
        <Button>Three</Button>
      </ButtonGroup>
      <ButtonGroup color="warning">
        <Button>One</Button>
        <Button>Two</Button>
        <Button>Three</Button>
      </ButtonGroup>
    </Box>
  );
}

Disabled​

Use the disabled prop to disable all the buttons.

The disabled prop is passed to the buttons, not the Button Group itself. Note that if you explicitly specify the disabled prop on the buttons directly, it will override what is used in the Button Group.

import { MdSettings } from 'react-icons/md';
import { Button, ButtonGroup, IconButton } from 'tailwind-joy/components';
import { iconClass } from 'tailwind-joy/utils';

export function ButtonGroupDisabled() {
  return (
    <ButtonGroup disabled>
      <Button>One</Button>
      <Button>Two</Button>
      <Button>Three</Button>
      <IconButton disabled={false}>
        <MdSettings className={iconClass()} />
      </IconButton>
    </ButtonGroup>
  );
}

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.

import { MdSettings } from 'react-icons/md';
import { Button, ButtonGroup, IconButton } from 'tailwind-joy/components';
import { iconClass } from 'tailwind-joy/utils';

export function ButtonGroupSpacing() {
  return (
    <ButtonGroup spacing="0.5rem">
      <Button>One</Button>
      <Button disabled>Two</Button>
      <Button>Three</Button>
      <IconButton>
        <MdSettings className={iconClass()} />
      </IconButton>
    </ButtonGroup>
  );
}

Vertical group​

The Button Group component can be displayed vertically using the orientation="vertical" prop.

import { MdSettings } from 'react-icons/md';
import { Box, Button, ButtonGroup, IconButton } from 'tailwind-joy/components';
import { iconClass } from 'tailwind-joy/utils';

export function ButtonGroupVertical() {
  return (
    <Box className="flex flex-wrap items-center justify-center gap-4">
      <ButtonGroup orientation="vertical" variant="solid">
        <Button>One</Button>
        <Button disabled>Two</Button>
        <Button>Three</Button>
        <IconButton>
          <MdSettings className={iconClass()} />
        </IconButton>
      </ButtonGroup>
      <ButtonGroup orientation="vertical" variant="soft">
        <Button>One</Button>
        <Button disabled>Two</Button>
        <Button>Three</Button>
        <IconButton>
          <MdSettings className={iconClass()} />
        </IconButton>
      </ButtonGroup>
      <ButtonGroup orientation="vertical" variant="outlined">
        <Button>One</Button>
        <Button disabled>Two</Button>
        <Button>Three</Button>
        <IconButton>
          <MdSettings className={iconClass()} />
        </IconButton>
      </ButtonGroup>
      <ButtonGroup orientation="vertical" variant="plain">
        <Button>One</Button>
        <Button disabled>Two</Button>
        <Button>Three</Button>
        <IconButton>
          <MdSettings className={iconClass()} />
        </IconButton>
      </ButtonGroup>
    </Box>
  );
}

Stretching button​

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

import { MdSettings } from 'react-icons/md';
import { Button, ButtonGroup, IconButton } from 'tailwind-joy/components';
import { iconClass } from 'tailwind-joy/utils';

export function ButtonGroupStretching1() {
  return (
    <ButtonGroup buttonFlex={1} className="w-[350px] max-w-full">
      <Button>One</Button>
      <Button>Two</Button>
      <Button>Three</Button>
      <IconButton>
        <MdSettings className={iconClass()} />
      </IconButton>
    </ButtonGroup>
  );
}

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

import { Button, ButtonGroup } from 'tailwind-joy/components';

export function ButtonGroupStretching2() {
  return (
    <ButtonGroup buttonFlex="0 1 200px" className="w-full justify-center">
      <Button>One</Button>
      <Button>Two</Button>
    </ButtonGroup>
  );
}

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 style prop.

Hue:0
import { useState } from 'react';
import { Box, Button, ButtonGroup } from 'tailwind-joy/components';

declare module 'react' {
  interface CSSProperties {
    '--ButtonGroup-separatorColor'?: string;
  }
}

export function ButtonGroupSeparatorColor() {
  const [hue, setHue] = useState('0');

  return (
    <Box className="flex flex-col items-center justify-center gap-4">
      <Box className="flex items-center gap-2">
        <span className="w-10 text-right">Hue:</span>
        <input
          type="range"
          name="hue-range"
          min="0"
          max="360"
          defaultValue="0"
          onChange={(e) => setHue(e.currentTarget.value)}
        />
        <span className="w-10 text-left">{hue}</span>
      </Box>
      <ButtonGroup
        variant="soft"
        style={{ '--ButtonGroup-separatorColor': `hsl(${hue} 100% 50%)` }}
      >
        <Button>One</Button>
        <Button>Two</Button>
        <Button>Three</Button>
      </ButtonGroup>
    </Box>
  );
}

Anatomy​

The Button Group component is composed of a single root <div> element that wraps around its contents:

<div role="group" class="tj-button-group-root ...">
  <!-- Button Group contents -->
</div>

API​

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