ButtonGroup
ButtonGroup joins related actions with the same visual emphasis into one compact, attached control.
Overview and decision boundary
Use ButtonGroup when adjacent actions form one compact, related set with the same visual variant.
Do not mix Button variants, group unrelated actions, or use it as a toolbar substitute.
import { ChevronDown } from "@nerio-ui/adapters/icons";import { Badge, ButtonGroup } from "@nerio-ui/ui";import { Button } from "@nerio-ui/ui/client";<ButtonGroup aria-label="Repository actions"> <Button badge={<Badge size="sm" tone="info">24</Badge>} variant="secondary"> Fork </Button> <Button icon={ChevronDown} aria-label="More fork actions" variant="secondary" /></ButtonGroup>Installation and imports
Install the editable registry source, or use the matching package entrypoint when the product keeps Nerio as a workspace dependency.
pnpm exec nerio add button-groupimport { ButtonGroup } from '@nerio-ui/ui';import { Button } from '@nerio-ui/ui/client';Usage
import { ButtonGroup } from '@nerio-ui/ui';import { Button } from '@nerio-ui/ui/client';<ButtonGroup aria-label="Document actions"> <Button variant="secondary">Cancel</Button> <Button variant="secondary">Save</Button></ButtonGroup>Variants
| Variant | Purpose |
|---|---|
Variant parity | Every child uses one Button variant. |
Anatomy
| Slot | Purpose |
|---|---|
button-group | Native group wrapper that owns one attached horizontal 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. |
divider | A short decorative separator distinguishes adjacent actions without a full border. |
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
- inherits Button motion
Accessibility
- 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.
Review the shared responsibility and evidence boundaries in the Accessibility foundation alongside this component-specific contract. Use the Spacing & layout foundation for shared density, wrapping, overflow, reflow, and component-versus-product ownership guidance. The Color foundation, Typography foundation, and Localization foundation define the shared visual-role, text-resilience, direction, and locale boundaries used by component examples.
API
| Prop | Values | Purpose |
|---|---|---|
children | ReactNode | Related Buttons that share one compact context and visual variant. |
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.
Related components
Tokens
| Group | Tokens | Controls |
|---|---|---|
Shape | --n-button-radius | Rounds only the outside corners of the group. |
Attachment | --n-button-border-width | Overlaps adjacent Button borders by one shared width. |
Divider | --n-button-group-divider | Draws a short, neutral separator between adjacent Buttons. |
Focus | --n-focus-ring | Keeps each child Button visibly focusable above adjacent borders. |