Orientation: horizontal | vertical is part of the public component contract.
Anatomy
button-groupfirst buttonlast button
Slot
Purpose
button-group
Native group wrapper that owns one attached horizontal or vertical layout.
button
Child Buttons retain their individual semantics, labels, and states.
button-badge
An optional count or status remains inside its child Button.
first / last button
Keep the group radius only on the outside corners.
shared border
Adjacent borders overlap so the controls read as one compact set.
States
State
Behavior
Default
Adjacent Buttons share a single compact visual boundary.
Hover and focus
The active child rises above neighbouring borders without losing its focus ring.
Disabled
Each child Button remains independently disabled when needed.
Loading
Each child Button can announce its own loading state without changing the group.
Motion
ButtonGroup adds no motion of its own; every child uses the shared Button motion and reduced-motion behavior.
inherits Button motion
Accessibility
Give the group a concise aria-label; every Button keeps its own visible name and independent Tab stop. ButtonGroup does not add arrow-key navigation, so use a keyboard-managed toolbar or selection control when that interaction is required.
Renders a group landmark by default; provide aria-label or aria-labelledby for its shared purpose.
Preserves the native semantics and independent Tab order of every child Button; it does not add roving focus or arrow-key navigation.
Use direct Nerio Button children with the same Button variant so the actions remain visually equal.
API
Prop
Values
Purpose
children
ReactNode
Related Buttons that share one compact context and visual variant.
orientation
"horizontal" | "vertical"
Horizontal is the default; vertical stacks direct Button children.
aria-label
string
Names the group for assistive technology.
aria-labelledby
string
Uses an existing visible label as the group name.
role
string
Defaults to group; keep group semantics for related actions.
className
string
Extends the group root without changing child Button contracts.
Implementation contract
Contract
Value
Registry item
button-group installs 4 Tailwind-first source files into the configured components directory.
Base UI
No interactive primitive required.
Registry dependencies
button
Package dependencies
clsx, react, tailwind-merge, tailwindcss
Styling contract
Contract
Value
Authoring
Complete, statically detectable Tailwind CSS v4 recipes own component visuals.
Values
Semantic and component --n-* variables remain the canonical customization layer.
Overrides
Customizable slots merge consumer className values with tailwindCn so conflicting utilities resolve deterministically.
Residual CSS
Only shared keyframes and scoped no-Preflight compatibility rules remain; there is no parallel visual selector layer.
Design notes
Use ButtonGroup when adjacent actions form one compact, related set with the same visual variant.
Do / do not
Do
Group direct Button children that share one local context and the same Button variant.
Do not
Mix Button variants, wrap children in layout elements, use ButtonGroup as a generic toolbar, or collect unrelated page actions.
