Button Group

Groups related buttons into a single segmented control, sharing variant, size, and state.

Usage

import { ButtonGroup } from '@appica/ui-react/button-group'
import { Button } from '@appica/ui-react/button'

<ButtonGroup variant="outline">
  <Button>Years</Button>
  <Button>Months</Button>
  <Button>Days</Button>
</ButtonGroup>

ButtonGroup is a thin wrapper around your existing Buttons. It collapses the inner corners and borders into one seamless control and shares variant, size, and disabled with every child through React context — so you set them once on the group instead of repeating them on each button.

Examples

Variants

Set variant on the group and every Button inherits it. Outlined variants (outline, primary-outline, light) overlap their shared borders so the seam stays a single hairline.

import { ButtonGroup } from '@appica/ui-react/button-group'
import { Button } from '@appica/ui-react/button'

const variants = ['primary', 'primary-outline', 'secondary', 'soft', 'outline', 'destructive'] as const

export default function ButtonGroupVariants() {
  return (
    <div className="flex flex-col items-center gap-4">
      {variants.map((variant) => (
        <ButtonGroup key={variant} variant={variant}>
          <Button>Years</Button>
          <Button>Months</Button>
          <Button>Days</Button>
        </ButtonGroup>
      ))}
    </div>
  )
}

Sizes

size cascades to the children too. Use it to scale the whole control at once.

import { ButtonGroup } from '@appica/ui-react/button-group'
import { Button } from '@appica/ui-react/button'

const sizes = ['sm', 'md', 'lg'] as const

export default function ButtonGroupSizes() {
  return (
    <div className="flex flex-col items-center gap-4">
      {sizes.map((size) => (
        <ButtonGroup key={size} size={size} variant="outline">
          <Button>Left</Button>
          <Button>Center</Button>
          <Button>Right</Button>
        </ButtonGroup>
      ))}
    </div>
  )
}

Vertical orientation

Set orientation="vertical" to stack the buttons; the group rounds the top and bottom of the stack instead of the left and right ends.

import { ButtonGroup } from '@appica/ui-react/button-group'
import { Button } from '@appica/ui-react/button'

export default function ButtonGroupOrientation() {
  return (
    <ButtonGroup orientation="vertical" variant="outline">
      <Button>Profile</Button>
      <Button>Billing</Button>
      <Button>Settings</Button>
    </ButtonGroup>
  )
}

Icon buttons

Pair an icon-* size with icon-only buttons to build a compact toolbar. Give each button an aria-label since there's no visible text.

import { ButtonGroup } from '@appica/ui-react/button-group'
import { Button } from '@appica/ui-react/button'
import { Bold, Italic, Underline } from '@appica/icons-react'

export default function ButtonGroupIconButtons() {
  return (
    <ButtonGroup variant="outline" size="icon-md">
      <Button aria-label="Bold">
        <Bold />
      </Button>
      <Button aria-label="Italic">
        <Italic />
      </Button>
      <Button aria-label="Underline">
        <Underline />
      </Button>
    </ButtonGroup>
  )
}

Split button

A common pattern: a primary action joined to a dropdown menu of related actions. The menu trigger is rendered as a Button, so it still inherits the group's variant through context even though it's nested inside DropdownMenu.

import { ButtonGroup } from '@appica/ui-react/button-group'
import { Button } from '@appica/ui-react/button'
import {
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuItem,
} from '@appica/ui-react/dropdown-menu'
import { ChevronDown } from '@appica/icons-react'

export default function ButtonGroupSplitButton() {
  return (
    <ButtonGroup variant="outline">
      <Button>Save</Button>
      <DropdownMenu>
        <DropdownMenuTrigger
          className="group/split"
          render={
            <Button size="icon-md" aria-label="More save options">
              <ChevronDown className="group-data-popup-open/split:rotate-180 motion-safe:transition-transform motion-safe:duration-200" />
            </Button>
          }
        />
        <DropdownMenuContent>
          <DropdownMenuItem>Save and continue</DropdownMenuItem>
          <DropdownMenuItem>Save as draft</DropdownMenuItem>
          <DropdownMenuItem>Save as template</DropdownMenuItem>
        </DropdownMenuContent>
      </DropdownMenu>
    </ButtonGroup>
  )
}

RTL

Every Appica UI component supports right-to-left layouts out of the box. Set the dir attribute on a container (commonly your <html> element) so CSS logical properties resolve correctly, and wrap your tree in DirectionProvider so direction-aware behavior — roving focus, popup placement, and the like — follows the same direction.

import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}

For setup details and caveats, see the RTL guide.

API reference

Prop	Type	Default	Description
`variant`	`'primary' \| 'primary-outline' \| 'secondary' \| 'soft' \| 'outline' \| 'ghost' \| 'destructive' \| 'light'`	—	Visual style applied to every child `Button`. Inherited unless a button sets its own `variant`.
`size`	`'sm' \| 'md' \| 'lg' \| 'icon-sm' \| 'icon-md' \| 'icon-lg'`	—	Height/padding applied to every child `Button`. Inherited unless a button sets its own `size`.
`orientation`	`'horizontal' \| 'vertical'`	`'horizontal'`	Lay the buttons out in a row or a column; controls which corners are rounded.
`disabled`	`boolean`	`false`	Disables every child `Button`. A child can't re-enable itself; the group's `disabled` wins.
`className`	`string`	—	Extra classes, merged after the group classes via `tailwind-merge`.

ButtonGroup renders a <div role="group"> and forwards every other prop (id, aria-*, ref, …) to it. Each child reads variant, size, and disabled from group context — a value set directly on a Button always overrides the group, except disabled, which is additive (the group disabling can't be overridden by a child).

Accessibility

Renders a <div role="group"> so assistive tech announces the buttons as one related set. Add an aria-label or aria-labelledby to name the group when its purpose isn't clear from context.
Each child remains a standalone Button, so focus order, Tab, Enter, and Space behave exactly as they do for a lone button.
Icon-only buttons have no text — give each one an aria-label.
disabled on the group removes every child from the tab order and sets data-disabled for styling.

Actions & Inputs

Data Display

Decoration & Effects

Layout

Menus

Navigation

Overlays

Status & Feedback