Button Group

Forms

Layout

Group buttons together with shared styling and toggle functionality. Includes ButtonGroup for layout and ToggleButtonGroup for selection state management.

Preview

Basic button grouping

Basic Button Group

Group related buttons together

Toggle Button Group

Single selection from a set of options

Text Alignment

Selected: center

View Mode

Multiple Selection

Allow selecting multiple options

Text Formatting

Selected: bold

Sizes

Different size variants

Small

Medium (default)

Large

Vertical Orientation

Stack buttons vertically

ButtonGroup

ToggleButtonGroup

Full Width

Buttons that fill available space

Props

Component API reference

ButtonGroup Props

Prop	Type	Default	Description
`children*`	`ReactNode`	—	Button components to group
`variant`	`'default' \| 'outline'`	`'default'`	Visual style
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Size of buttons
`orientation`	`'horizontal' \| 'vertical'`	`'horizontal'`	Layout orientation
`disabled`	`boolean`	`false`	Disable all buttons
`fullWidth`	`boolean`	`false`	Fill container width

ToggleButtonGroup Props

Prop	Type	Default	Description
`options*`	`{ value: string; label: ReactNode }[]`	—	Available options
`value*`	`string \| string[]`	—	Selected value(s)
`onChange*`	`(value: string \| string[]) => void`	—	Change handler
`multiple`	`boolean`	`false`	Allow multiple selections
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Size variant
`orientation`	`'horizontal' \| 'vertical'`	`'horizontal'`	Layout orientation
`disabled`	`boolean`	`false`	Disable all buttons
`fullWidth`	`boolean`	`false`	Fill container width

Usage

Import and implementation example

import { ButtonGroup, ToggleButtonGroup } from '@/components/ui/button-group'
import { Button } from '@/components/ui/button'
import { AlignLeft, AlignCenter, AlignRight } from 'lucide-react'

export default function Example() {
  const [alignment, setAlignment] = useState('center')
  const [formatting, setFormatting] = useState(['bold'])

  return (
    <>
      {/* Basic ButtonGroup */}
      <ButtonGroup>
        <Button variant="inverse">Left</Button>
        <Button variant="inverse">Center</Button>
        <Button variant="inverse">Right</Button>
      </ButtonGroup>

      {/* Toggle selection (single) */}
      <ToggleButtonGroup
        options={[
          { value: 'left', label: <AlignLeft /> },
          { value: 'center', label: <AlignCenter /> },
          { value: 'right', label: <AlignRight /> },
        ]}
        value={alignment}
        onChange={setAlignment}
      />

      {/* Multiple selection */}
      <ToggleButtonGroup
        options={[
          { value: 'bold', label: 'B' },
          { value: 'italic', label: 'I' },
        ]}
        value={formatting}
        onChange={setFormatting}
        multiple
      />
    </>
  )
}

This block is self-contained (no UI component dependencies)

Features

Built-in functionality

ButtonGroup: Wrapper for any Button components with shared border radius
ToggleButtonGroup: Built-in selection state management
Multiple selection: Allow selecting multiple options at once
Three sizes: Small, medium, and large variants
Orientation: Horizontal or vertical layouts
Full width: Fill available container width
Accessible: ARIA roles for radio/checkbox groups
Dark mode: Full dark mode support

Accessibility

Accessibility considerations

ARIA Attributes

ButtonGroup uses role="group"ToggleButtonGroup uses role="radiogroup" or role="group"Options use role="radio" or role="checkbox" based on multiple proparia-checked indicates selection state

Keyboard Navigation

Key	Action
`Tab`	Navigate between buttons
`Enter / Space`	Toggle selection

Notes

Focus ring visible on keyboard navigation
Selected state indicated by color and aria-checked
Disabled state prevents interaction
Labels support icons and text

Related Components

Button Toggle Toggle Group Segmented Control