Skip to content
Browse documentation
whisk/ui

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.

Coming from another library?
Use 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

PropTypeDefaultDescription
orientationhorizontal | verticalhorizontalChoose the visual axis. It does not change keyboard navigation between buttons.
attachedbooleanfalseJoin direct visible Button borders into a single visual treatment.
variantprimary | secondary | ghost | outline | destructive | ghostDestructivenoneProvide a visual default only to direct Button children that do not set their own variant.
sizesm | md | lgnoneProvide a size default only to direct Button children that do not set their own size.
aria-labelstringnoneGive the action group an accessible name when its purpose is not already clear in context.
aria-labelledbystringnoneGive the action group an accessible name when its purpose is not already clear in context.

Shared props

PropSupportedNotes
as / asChildYesChoose the group host with as, or merge ButtonGroup presentation into exactly one element child with asChild.
Style propsYesUse the shared static style-prop surface. See Style props.
className / styleYesApplied to the rendered group or child host.
refYesForwards to the rendered group or child host.
Native HTML attributesYesNative div attributes are forwarded, except props ButtonGroup owns for its group semantics.

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.

DoDon't
Save draft / PublishYes / No; two primary or two destructive actions in one group