Skip to contentSkip to navigationSkip to topbar
Paste assistant Assistant
Figma
Star

Button Group

Version 4.1.0GithubStorybookPeer review pending

A Button Group is a component used to render groups of Buttons.

Component preview theme
const BasicButtonGroup = () => {
return (
<ButtonGroup attached>
<Button variant="secondary">
<PlusIcon decorative />
Add
</Button>
<Button variant="secondary">
<EditIcon decorative />
Edit
</Button>
<Button variant="secondary">
<ExportIcon decorative />
Export
</Button>
<Button variant="destructive_secondary">
<DeleteIcon decorative />
Delete
</Button>
</ButtonGroup>
);
};
render(<BasicButtonGroup />);

Guidelines

Guidelines page anchor

A Button Group is a way to bring a set of 2-6 buttons together, often visually, that have related actions. The buttons should be independent from each other, i.e. clicking one button does not change the state of another button.

Any Paste components that use Button, including Popover, Modal, and Minimizable Dialog can be put into a ButtonGroup.

Button Group vs Radio Button Group

Button Group vs Radio Button Group page anchor

Button groups should be used to help bring together a group of related actions, rather than selecting from a set of options. Use a Radio Button Group to allow the user to select a single option from a group of mutually exclusive choices. Radio Buttons cannot be used within a Button Group.

By default, the Buttons in a Button Group are displayed horizontally with a margin between them.

Component preview theme
const BasicButtonGroup = () => {
return (
<ButtonGroup>
<Button variant="secondary">
<PlusIcon decorative />
Add
</Button>
<Button variant="secondary">
<EditIcon decorative />
Edit
</Button>
<Button variant="secondary">
<ExportIcon decorative />
Export
</Button>
<Button variant="destructive_secondary">
<DeleteIcon decorative />
Delete
</Button>
</ButtonGroup>
);
};
render(<BasicButtonGroup />);

Use the attached prop to make the buttons visually connected.

Component preview theme
const BasicButtonGroup = () => {
return (
<ButtonGroup attached>
<Button variant="secondary">
<PlusIcon decorative />
Add
</Button>
<Button variant="secondary">
<EditIcon decorative />
Edit
</Button>
<Button variant="secondary">
<ExportIcon decorative />
Export
</Button>
<Button variant="destructive_secondary">
<DeleteIcon decorative />
Delete
</Button>
</ButtonGroup>
);
};
render(<BasicButtonGroup />);

Use the icon variant when space is limited and the icons being used are easily recognizable (e.g., icons representing graph types). It is highly recommended to pair this variant with the Tooltip component to help ensure understandability.

Component preview theme
const IconButtonGroup = () => {
const [boldPressed, setBoldPressed] = React.useState(false);
const [italicPressed, setItalicPressed] = React.useState(false);
const [underlinePressed, setUnderlinePressed] = React.useState(false);
return (
<ButtonGroup attached>
<Tooltip text="Bold">
<Button
variant="secondary_icon"
size="icon"
pressed={boldPressed}
onClick={() => setBoldPressed(!boldPressed)}
>
<BoldIcon decorative={false} title="Bold" />
</Button>
</Tooltip>
<Tooltip text="Italic">
<Button
variant="secondary_icon"
size="icon"
pressed={italicPressed}
onClick={() => setItalicPressed(!italicPressed)}
>
<ItalicIcon decorative={false} title="Italic" />
</Button>
</Tooltip>
<Tooltip text="Underline">
<Button
variant="secondary_icon"
size="icon"
pressed={underlinePressed}
onClick={() => setUnderlinePressed(!underlinePressed)}
>
<UnderlineIcon decorative={false} title="Underline" />
</Button>
</Tooltip>
</ButtonGroup>
);
};
render(<IconButtonGroup />);

Use a Menu to include more actions in the ButtonGroup, such as when there is limited space or there are more than 6 actions.

Component preview theme
const MenuButtonGroup = () => {
const menu = useMenuState();
return (
<ButtonGroup attached>
<Button variant="secondary">
<PlusIcon decorative />
Add
</Button>
<Button variant="secondary">
<EditIcon decorative />
Edit
</Button>
<Button variant="destructive_secondary">
<DeleteIcon decorative />
Delete
</Button>
<MenuButton {...menu} variant="secondary">
<ChevronDownIcon decorative={false} title='Additional actions' />
</MenuButton>
<Menu {...menu} aria-label="Additional actions">
<MenuItem {...menu}>Export</MenuItem>
<MenuItem {...menu}>Share</MenuItem>
<MenuItem {...menu}>Duplicate</MenuItem>
</Menu>
</ButtonGroup>
);
};
render(<MenuButtonGroup />);
Component preview theme
const DisabledButtonGroup = () => {
return (
<ButtonGroup attached>
<Button variant="secondary" disabled>
<PlusIcon decorative />
Add
</Button>
<Button variant="secondary" disabled>
<EditIcon decorative />
Edit
</Button>
<Button variant="secondary" disabled>
<ExportIcon decorative />
Export
</Button>
<Button variant="destructive_secondary" disabled>
<DeleteIcon decorative />
Delete
</Button>
</ButtonGroup>
);
};
render(<DisabledButtonGroup />);

Button Groups:

  • Should have between 2–6 options
  • Are comprised of independent buttons
  • Labels should use sentence case