Skip to content
FelicityUI

Button Group

A container that groups related buttons together with consistent styling.

Installation

terminal
npx felicityui add button-group --platform react

Usage

example.tsx
import { Button } from "@/components/ui/button"
import {
  ButtonGroup,
  ButtonGroupSeparator,
  ButtonGroupText,
} from "@/components/ui/button-group"

<ButtonGroup aria-label="Button group">
  <Button variant="outline">Button 1</Button>
  <Button variant="outline">Button 2</Button>
</ButtonGroup>

Composition

ButtonGroup
├── Button or Input
├── ButtonGroupSeparator
└── ButtonGroupText

Use ButtonGroup for actions. Use ToggleGroup when options toggle a state.

Composition

ButtonGroup
├── Button or Input
├── ButtonGroupSeparator
└── ButtonGroupText

Usage

import { Button } from "@/components/ui/button"
import {
  ButtonGroup,
  ButtonGroupSeparator,
  ButtonGroupText,
} from "@/components/ui/button-group"

<ButtonGroup aria-label="Button group">
  <Button variant="outline">Button 1</Button>
  <Button variant="outline">Button 2</Button>
</ButtonGroup>

Accessibility

  • Root has role="group".
  • Tab moves between buttons in the group.
  • Label the group with aria-label or aria-labelledby.

Felicity treatment: paper/ink surfaces, copper accent sparingly, hairline borders, logical (RTL-safe) border joining.

Default

Joined outline buttons that share one border. Label the group for assistive tech.

Orientation

Use orientation="vertical" to stack joined controls.

Separator

Outline actions with a separator between related controls.

Split

Primary action plus a secondary control, divided by a separator.

Nested

Nest ButtonGroups to keep joined clusters with spacing between them.

With text

ButtonGroupText for labels or addons inside the group.

https://

API Reference

PropTypeDefaultDescription
orientationhorizontal | verticalhorizontalLayout direction for joined children.
segmentedbooleanfalseOptional Felicity segmented chrome. Prefer ToggleGroup for state toggles.
ButtonGroupSeparator.orientationhorizontal | verticalverticalSeparator axis (vertical is a thin rule between horizontal buttons).
ButtonGroupText.renderReactElement—Optional element to render as the text host (e.g. Label).
classNamestring—Additional classes.

Accessibility

WCAG 2.2 AA

  • Exposed as role=group.
  • Buttons remain individually focusable via Tab.
  • Group has an accessible name (aria-label or aria-labelledby).
  • Separator is presentational (role=separator) and does not steal focus.

Platform notes

React

Native HTML role=group with Felicity tokens. Joins child control borders; no Base UI / Radix runtime.

  • Server Component compatible.
  • Use aria-label or aria-labelledby on the group.
  • Prefer ToggleGroup when items toggle state rather than fire actions.
  • ButtonGroupText supports a render prop to compose Label or other elements.