ButtonGroup
Lay out related actions as a group.
Overview
ButtonGroup presents a small set of related actions as one labelled group. It can align Buttons, attach their borders, and provide visual defaults without changing each Button's behavior.
attached, not isAttached. ButtonGroup has no separator or text sub-components; it only styles its direct Button children.Use when
A small set of related buttons needs shared alignment, size, or attached borders.
Use instead
Use StackRow for unrelated actions, SegmentedControl for a mutually exclusive selection, or InputGroup to attach a Button to an input.
Usage
import { Button, ButtonGroup } from "@smoothie-framework/whisk-react";
<ButtonGroup aria-label="Document actions">
<Button>Save document</Button>
<Button variant="secondary">Cancel</Button>
</ButtonGroup>Examples
Variants
Set variant on the group for a shared default. An individual Button can override it for the primary action.
import { Button, ButtonGroup } from "@smoothie-framework/whisk-react";
<ButtonGroup aria-label="Publishing actions" variant="outline">
<Button>Cancel</Button>
<Button>Save draft</Button>
<Button variant="primary">Publish</Button>
</ButtonGroup>Sizes
Set size on the group to give its direct Buttons a shared size.
import { Button, ButtonGroup, Stack } from "@smoothie-framework/whisk-react";
<Stack gap={3}>
<ButtonGroup aria-label="Small actions" size="sm">
<Button>Save draft</Button>
<Button variant="secondary">Preview</Button>
</ButtonGroup>
<ButtonGroup aria-label="Medium actions" size="md">
<Button>Save draft</Button>
<Button variant="secondary">Preview</Button>
</ButtonGroup>
<ButtonGroup aria-label="Large actions" size="lg">
<Button>Save draft</Button>
<Button variant="secondary">Preview</Button>
</ButtonGroup>
</Stack>Attached
Use attached when adjacent actions form one compact control. The Buttons remain separate actions with separate focus stops.
import { Button, ButtonGroup } from "@smoothie-framework/whisk-react";
<ButtonGroup attached aria-label="File actions">
<Button variant="outline">Copy</Button>
<Button variant="outline">Move</Button>
<Button variant="outline">Archive</Button>
</ButtonGroup>Orientation
Use orientation="vertical" when a short action set reads better as a column.
import { Button, ButtonGroup } from "@smoothie-framework/whisk-react";
<ButtonGroup
aria-label="Export actions"
orientation="vertical"
variant="secondary"
>
<Button>Export PDF</Button>
<Button>Export CSV</Button>
</ButtonGroup>Icons
Use an attached icon toolbar when each action is recognizable from its accessible name.
import { ArrowsClockwiseIcon, MinusIcon, PlusIcon } from "@smoothie-framework/whisk-react/icons";
import { Button, ButtonGroup } from "@smoothie-framework/whisk-react";
<ButtonGroup attached aria-label="Zoom">
<Button iconOnly aria-label="Zoom out">
<MinusIcon />
</Button>
<Button iconOnly aria-label="Reset zoom">
<ArrowsClockwiseIcon />
</Button>
<Button iconOnly aria-label="Zoom in">
<PlusIcon />
</Button>
</ButtonGroup>Split button
Keep the main action visible and place less-common export formats in a menu.
import { ChevronDownIcon } from "@smoothie-framework/whisk-react/icons";
import {
Button,
ButtonGroup,
DropdownMenu,
DropdownMenuContent,
DropdownMenuItem,
DropdownMenuTrigger,
} from "@smoothie-framework/whisk-react";
<DropdownMenu>
<ButtonGroup attached aria-label="Export">
<Button>Export</Button>
<DropdownMenuTrigger asChild>
<Button iconOnly aria-label="More export options">
<ChevronDownIcon />
</Button>
</DropdownMenuTrigger>
</ButtonGroup>
<DropdownMenuContent>
<DropdownMenuItem>Export as PDF</DropdownMenuItem>
<DropdownMenuItem>Export as CSV</DropdownMenuItem>
</DropdownMenuContent>
</DropdownMenu>Disabled
Set disabled on an individual Button when one group action is unavailable.
import { Button, ButtonGroup } from "@smoothie-framework/whisk-react";
<ButtonGroup aria-label="Publish actions">
<Button>Save draft</Button>
<Button disabled>Publish</Button>
</ButtonGroup>Props
Component props
Shared props
Accessibility
ButtonGroup renders role="group" and keeps each Button in the ordinary Tab order. Give the group an aria-label or aria-labelledby when its purpose is not clear nearby. It does not provide toolbar arrow-key navigation or radio-style selection; use an appropriate toolbar pattern when arrow-key navigation is needed. Keep every Button label specific, and keep a destructive action visually and verbally distinct from the primary action.
Content guidance
Keep related labels parallel. Make the primary action specific and visually distinct.