ButtonGroup
Join related buttons into one visual control set.
Anatomy#
The group owns its separators; the caller supplies the child Buttons and their content.
Usage#
Use ButtonGroup when adjacent actions should read as one control set. Each child remains its own interactive control; the group supplies layout and shared presentation. Use ToggleButton inside the group for independently pressed actions. ButtonGroup does not coordinate selection or add toolbar keyboard navigation.
Composition#
Root size (sm, md, lg; default md), variant (default solid), and tone (default
primary) set defaults for every descendant Button. A Button can override any of them. orientation
(horizontal by default, or vertical) sets the layout direction. Compose a menu or popover trigger
as a child when an action needs an overlay.
The root renders a div with role="group", so give it an aria-label. Set role="toolbar" only
if you also provide the toolbar keyboard behavior.
Separator#
Insert ButtonGroup.Separator only where an explicit boundary is useful. Its orientation is
perpendicular to the group axis: vertical in a horizontal group and horizontal in a vertical group.
It renders a div with role="separator".
Examples#
Group document actions#
Join copy, duplicate, and archive so they read as one set of file commands.
Format selected text#
Compose ToggleButton children for independently pressed actions. They inherit the group’s size,
tone, and variant (the unpressed appearance); activeVariant controls each button’s pressed
appearance.
Split clipboard actions#
Use a separator to distinguish copy from paste without changing either button’s semantics.
Export a report with format options#
Keep the primary export command on a Button and attach extra formats through a dropdown trigger.
Save a document with extra options#
Attach a popover trigger when the extra action opens a short panel rather than a menu of commands.
Zoom a canvas from a vertical toolbar#
Set orientation="vertical" for stacked icon controls such as zoom.
API Reference#
Attributes#
data-orientationProps#
ButtonGroup#
Props for the ButtonGroup component. Renders a <div> element by default.
Separator#
Props for the ButtonGroup.Separator component. Renders a <div> element by default.