Primitives

Button Group

Visually-joined cluster of buttons sharing borders.

Preview

import { Button } from '@brika/clay/components/button';
import { ButtonGroup } from '@brika/clay/components/button-group';

/** Three related action buttons joined in a shared frame, each click fires once, no selection state. */
export default function ButtonGroupDefaultDemo() {
  return (
    <ButtonGroup>
      <Button variant="outline">Reply</Button>
      <Button variant="outline">Reply all</Button>
      <Button variant="outline">Forward</Button>
    </ButtonGroup>
  );
}

01 Installation

Install

Pull Button Group from the barrel for everyday use, or the granular path when you want a tighter bundle.

tsxBarrel1 line

import { ButtonGroup } from "@brika/clay";

tsxGranular1 line

import { ButtonGroup } from "@brika/clay/components/button-group";

02 Usage

A minimal example

Drop this into a page. Native HTML attributes pass through to the underlying primitive.

tsxButton Group.tsx13 lines

import { Button } from '@brika/clay/components/button';
import { ButtonGroup } from '@brika/clay/components/button-group';

/** Three related action buttons joined in a shared frame, each click fires once, no selection state. */
export default function ButtonGroupDefaultDemo() {
  return (
    <ButtonGroup>
      <Button variant="outline">Reply</Button>
      <Button variant="outline">Reply all</Button>
      <Button variant="outline">Forward</Button>
    </ButtonGroup>
  );
}

03 Examples

Button Group, every way

Filled

Filled default variant inside a group, good for primary action clusters.

GitHub

import { Button } from '@brika/clay/components/button';
import { ButtonGroup } from '@brika/clay/components/button-group';

/** Filled default variant inside a group, good for primary action clusters. */
export default function ButtonGroupFilledDemo() {
  return (
    <ButtonGroup>
      <Button>Edit</Button>
      <Button>Preview</Button>
      <Button>Share</Button>
    </ButtonGroup>
  );
}

Icons

Icon-only action buttons for a compact toolbar, every button needs an `aria-label`.

GitHub

import { Button } from '@brika/clay/components/button';
import { ButtonGroup } from '@brika/clay/components/button-group';
import { ClipboardPaste, Copy, Scissors } from 'lucide-react';

/** Icon-only action buttons for a compact toolbar, every button needs an `aria-label`. */
export default function ButtonGroupIconsDemo() {
  return (
    <ButtonGroup>
      <Button variant="outline" size="icon" aria-label="Cut">
        <Scissors />
      </Button>
      <Button variant="outline" size="icon" aria-label="Copy">
        <Copy />
      </Button>
      <Button variant="outline" size="icon" aria-label="Paste">
        <ClipboardPaste />
      </Button>
    </ButtonGroup>
  );
}

Split Button

Primary action plus a dropdown chevron for related variants.

GitHub

import { Button } from '@brika/clay/components/button';
import { ButtonGroup } from '@brika/clay/components/button-group';
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuTrigger,
} from '@brika/clay/components/dropdown-menu';
import { ChevronDown } from 'lucide-react';

/** Primary action plus a dropdown chevron for related variants. */
export default function ButtonGroupSplitDemo() {
  return (
    <ButtonGroup>
      <Button>Save changes</Button>
      <DropdownMenu>
        <DropdownMenuTrigger asChild>
          <Button size="icon" aria-label="More save options">
            <ChevronDown />
          </Button>
        </DropdownMenuTrigger>
        <DropdownMenuContent align="end">
          <DropdownMenuItem>Save as draft</DropdownMenuItem>
          <DropdownMenuItem>Save and publish</DropdownMenuItem>
          <DropdownMenuItem>Save a copy</DropdownMenuItem>
        </DropdownMenuContent>
      </DropdownMenu>
    </ButtonGroup>
  );
}

Vertical

Vertical orientation stacks buttons top-to-bottom with shared dividers.

GitHub

import { Button } from '@brika/clay/components/button';
import { ButtonGroup } from '@brika/clay/components/button-group';

/** Vertical orientation stacks buttons top-to-bottom with shared dividers. */
export default function ButtonGroupVerticalDemo() {
  return (
    <ButtonGroup orientation="vertical">
      <Button variant="outline">New file</Button>
      <Button variant="outline">Open folder</Button>
      <Button variant="outline">Recent</Button>
    </ButtonGroup>
  );
}

With Input

Input + trailing button, classic copy-URL pattern.

GitHub

import { Button } from '@brika/clay/components/button';
import { ButtonGroup } from '@brika/clay/components/button-group';
import { Input } from '@brika/clay/components/input';
import { Copy } from 'lucide-react';

/** Input + trailing button, classic copy-URL pattern. */
export default function ButtonGroupWithInputDemo() {
  return (
    <ButtonGroup className="w-full max-w-sm">
      <Input readOnly value="https://clay.brika.dev/share/abc123" />
      <Button variant="outline" size="icon" aria-label="Copy URL">
        <Copy />
      </Button>
    </ButtonGroup>
  );
}

04 Accessibility

Accessibility

The wrapper carries role="group", add aria-label when the group's purpose is not clear from context.
Each button inside the group keeps its individual focus ring and keyboard behavior.
Icon-only buttons inside the group still require aria-label.

05 Tokens 4 theme-overridable

Theme tokens

Every CSS variable Button Group reads, with its default and the dotted path you'd write in a ThemeConfig JSON to override it. Set any of these in your theme to retune Button Group without touching component code.

Button Group tokens

4 tokens

ColorFill, border, and text colors.4

--button-group-frame-containercolorvar(--input-container)
components.buttonGroup.frameContainer
Background fill of the button-group frame. Defaults to the `--input-container` role so a group reads as a single grouped control matching other inputs.
--button-group-frame-bordercolorvar(--input-border)
components.buttonGroup.frameBorder
Border color of the button-group outer frame. Defaults to the `--input-border` role so the frame matches other input edges.
--button-group-divider-colorcolorvar(--input-border)
components.buttonGroup.dividerColor
Color of the 1px separator drawn between adjacent buttons in the group, and of the explicit `ButtonGroupSeparator` bar. Defaults to `--input-border` so dividers blend with the frame.
--button-group-text-colorcolorvar(--muted-foreground)
components.buttonGroup.textColor
Foreground color of the inline `ButtonGroupText` label slot. Defaults to the muted-foreground role so plain text inside a group reads as supporting content.

Override in a theme

Authoring a theme is plain JSON. Drop overrides under components.buttonGroup, the names are camelCase versions of the variable suffix.

jsonmy-theme.json12 lines

{
  "id": "my-theme",
  "name": "My Theme",
  "description": "...",
  "accentSwatches": ["#000"],

  "components": {
    "buttonGroup": {
      "frameContainer": "var(--input-container)"
    }
  }
}

Then apply with applyTheme(myTheme) (see the theming guide), scope it to a subtree with themeToCssVars(myTheme, mode), or consume any token directly in your own JSX with the matching Tailwind utility (e.g. bg-button-group-…) — see the chips on each token row.

06 API reference

API reference

Props specific to Button Group. Native HTML attributes pass through to the underlying primitive, see the component source on GitHub for the full type signature.

<ButtonGroup />

1 prop

orientation
'horizontal' | 'vertical'
Lay buttons out horizontally or vertically.

<ButtonGroupSeparator />

passthrough

No wrapper-specific props, all attributes pass through to the underlying primitive.

<ButtonGroupText />

1 prop

asChilddefault false
boolean
When true, render the child element instead of the default DOM node and merge props. Lets you compose with <a>, <Link>, or another primitive while keeping behavior and styling.