Button Group

Installation#

# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add button-group

Usage#

import { ButtonGroup, ButtonGroupItem } from "@/components/ui/button-group"

export function Example() {
  return (
    <ButtonGroup>
      <ButtonGroupItem>Day</ButtonGroupItem>
      <ButtonGroupItem>Week</ButtonGroupItem>
      <ButtonGroupItem>Month</ButtonGroupItem>
    </ButtonGroup>
  )
}

Attached vs Detached#

By default, attached fuses buttons into a single pill: interior border radii are stripped and every item after the first drops its left border, so neighbours share one 1px stroke instead of stacking two. Set attached={false} for a spaced layout where each button keeps its own rounding.

Variants#

The variant prop on ButtonGroup is inherited by every ButtonGroupItem inside it. Supports all the same variants as Button.

Sizes#

Inherits the same three sizes as Button - sm (32px), md (36px, the default), and lg (40px).

Density#

density tightens the group for application UI - the same axis as Button and the rest of Koala. Set it per-group or for a whole subtree with DensityProvider. See Density.

Icon-only#

Set iconOnly on each item to collapse it to a square. Always pass an aria-label - Koala warns in development if one is missing.

Per-item overrides#

Any prop set directly on a ButtonGroupItem overrides the group context. Mix variants within the same group to give one action more visual weight - keep all items the same surface style (both bordered, or both filled) so the joined edges look intentional.

FAQ#