# Button Group

A container that groups related buttons together with consistent styling.

Source: https://webjs.dev/ui/docs/components/button-group

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import { buttonGroupClass } from '#components/ui/button-group.ts';
import {
  ArchiveIcon, ArrowLeftIcon, CalendarPlusIcon, ClockIcon, ListFilterIcon,
  MailCheckIcon, MoreHorizontalIcon, TagIcon, Trash2Icon,
} from '#lib/ui/lucide.ts';

export default function ButtonGroupDemo() {
  return html`
    <div role="group" data-slot="button-group" data-orientation="horizontal" class=${buttonGroupClass()}>
      <div role="group" data-slot="button-group" data-orientation="horizontal" class=${cn(buttonGroupClass(), 'hidden sm:flex')}>
        <button type="button" data-slot="button" data-variant="outline" data-size="icon" aria-label="Go Back" class=${buttonClass({ variant: 'outline', size: 'icon' })}>
          ${ArrowLeftIcon()}
        </button>
      </div>
      <div role="group" data-slot="button-group" data-orientation="horizontal" class=${buttonGroupClass()}>
        <button type="button" data-slot="button" data-variant="outline" data-size="default" class=${buttonClass({ variant: 'outline' })}>Archive</button>
        <button type="button" data-slot="button" data-variant="outline" data-size="default" class=${buttonClass({ variant: 'outline' })}>Report</button>
      </div>
      <div role="group" data-slot="button-group" data-orientation="horizontal" class=${buttonGroupClass()}>
        <button type="button" data-slot="button" data-variant="outline" data-size="default" class=${buttonClass({ variant: 'outline' })}>Snooze</button>
        <button type="button" id="button-group-demo-more" data-slot="button" data-variant="outline" data-size="icon" aria-label="More Options" class=${buttonClass({ variant: 'outline', size: 'icon' })}>
          ${MoreHorizontalIcon()}
        </button>
      </div>
    </div>
    <ui-dropdown-menu trigger="button-group-demo-more" class="absolute">
      <ui-dropdown-menu-content align="end" class="w-40">
        <ui-dropdown-menu-group>
          <ui-dropdown-menu-item>
            ${MailCheckIcon()}
            Mark as Read
          </ui-dropdown-menu-item>
          <ui-dropdown-menu-item>
            ${ArchiveIcon()}
            Archive
          </ui-dropdown-menu-item>
        </ui-dropdown-menu-group>
        <ui-dropdown-menu-separator></ui-dropdown-menu-separator>
        <ui-dropdown-menu-group>
          <ui-dropdown-menu-item>
            ${ClockIcon()}
            Snooze
          </ui-dropdown-menu-item>
          <ui-dropdown-menu-item>
            ${CalendarPlusIcon()}
            Add to Calendar
          </ui-dropdown-menu-item>
          <ui-dropdown-menu-item>
            ${ListFilterIcon()}
            Add to List
          </ui-dropdown-menu-item>
          <ui-dropdown-menu-sub>
            <ui-dropdown-menu-sub-trigger>
              ${TagIcon()}
              Label As...
            </ui-dropdown-menu-sub-trigger>
            <ui-dropdown-menu-sub-content>
              <ui-dropdown-menu-group aria-label="Label As">
                <ui-dropdown-menu-item type="radio" value="personal" checked>Personal</ui-dropdown-menu-item>
                <ui-dropdown-menu-item type="radio" value="work">Work</ui-dropdown-menu-item>
                <ui-dropdown-menu-item type="radio" value="other">Other</ui-dropdown-menu-item>
              </ui-dropdown-menu-group>
            </ui-dropdown-menu-sub-content>
          </ui-dropdown-menu-sub>
        </ui-dropdown-menu-group>
        <ui-dropdown-menu-separator></ui-dropdown-menu-separator>
        <ui-dropdown-menu-group>
          <ui-dropdown-menu-item variant="destructive">
            ${Trash2Icon()}
            Trash
          </ui-dropdown-menu-item>
        </ui-dropdown-menu-group>
      </ui-dropdown-menu-content>
    </ui-dropdown-menu>
  `;
}
```

## Installation

```bash
npx @webjsdev/ui add button-group
```

### Copy and paste the following code into your project.

````ts title="components/ui/button-group.ts"
/**
 * Button group: a row (or column) of buttons that share their borders, so
 * they read as one control. Tier-1 class helper; compose with a real
 * container element and real buttons.
 *
 * shadcn parity:
 *   ButtonGroup (orientation: horizontal | vertical)
 *                          → buttonGroupClass({ orientation }), alias buttonGroupVariants
 *   ButtonGroupText        → buttonGroupTextClass()
 *   ButtonGroupSeparator   → buttonGroupSeparatorClass() with separatorClass({ orientation })
 *
 * The group flattens the inner corners and drops the doubled border between
 * neighbours, by logical side, so it reads correctly under `dir="rtl"`. A
 * nested group (a group of groups) keeps its own gap.
 *
 * A11y (required for accessible output): put `role="group"` on the container
 * and name it with `aria-label` (or `aria-labelledby`) when the buttons share
 * a purpose a screen-reader user needs to hear ("Text alignment"). Each button
 * keeps its own accessible name; an icon-only one needs `aria-label`. Set
 * `data-orientation` to match the orientation you pass, and a separator inside
 * the group is decorative, so give it `role="none"` or `aria-hidden="true"`.
 *
 * Design tokens used: --border, --input, --muted.
 *
 * @example
 * ```html
 * <div class=${buttonGroupClass()} role="group" aria-label="Text alignment" data-orientation="horizontal">
 *   <button class=${buttonClass({ variant: 'outline' })} type="button">Left</button>
 *   <button class=${buttonClass({ variant: 'outline' })} type="button">Center</button>
 *   <button class=${buttonClass({ variant: 'outline' })} type="button">Right</button>
 * </div>
 * ```
 */
import { cn } from '../lib/utils.ts';

const BASE =
  "has-[>[data-slot=button-group]]:gap-2 [&>*]:focus-visible:relative [&>*]:focus-visible:z-10 has-[select[aria-hidden=true]:last-child]:[&>[data-slot=select-trigger]:last-of-type]:rounded-e-md group/button-group flex w-fit items-stretch *:focus-visible:relative *:focus-visible:z-10 [&>[data-slot=select-trigger]:not([class*='w-'])]:w-fit [&>input]:flex-1";

const ORIENTATIONS = {
  horizontal:
    '[&>*:not(:first-child)]:rounded-s-none [&>*:not(:first-child)]:border-s-0 [&>*:not(:last-child)]:rounded-e-none',
  vertical:
    'flex-col [&>*:not(:first-child)]:rounded-t-none [&>*:not(:first-child)]:border-t-0 [&>*:not(:last-child)]:rounded-b-none',
} as const;

export type ButtonGroupOrientation = keyof typeof ORIENTATIONS;

/** The group container. Pair with `role="group"` and `data-orientation`. */
export function buttonGroupClass(opts: { orientation?: ButtonGroupOrientation } & { className?: string } = {}): string {
  return cn(BASE, ORIENTATIONS[opts.orientation ?? 'horizontal'], opts.className);
}

/**
 * shadcn's name for {@link buttonGroupClass}, so shadcn code ports verbatim
 * (`buttonGroupVariants({ ... })` is shadcn's `cva` export for `ButtonGroup`).
 * Like cva, it merges a `className` into the result.
 */
export function buttonGroupVariants(opts: { orientation?: ButtonGroupOrientation } & { className?: string } = {}): string {
  return buttonGroupClass(opts);
}

/** A non-interactive label or value sitting inside the group. */
export function buttonGroupTextClass(): string {
  return "gap-2 rounded-md border bg-muted px-4 text-sm font-medium shadow-xs [&_svg:not([class*='size-'])]:size-4 flex items-center [&_svg]:pointer-events-none";
}

/**
 * A divider between buttons. Compose with the separator helper:
 * `cn(separatorClass({ orientation: 'vertical' }), buttonGroupSeparatorClass())`.
 */
export function buttonGroupSeparatorClass(): string {
  return 'm-0! bg-input data-[orientation=vertical]:h-auto relative self-stretch data-horizontal:mx-px data-horizontal:w-auto data-vertical:my-px data-vertical:h-auto';
}
````

### Update the import paths to match your project setup.

## Usage

```ts
import {
  buttonGroupClass,
  buttonGroupSeparatorClass,
  buttonGroupTextClass,
} from '#components/ui/button-group.ts';
```

```ts
<div role="group" data-slot="button-group" data-orientation="horizontal" class=${buttonGroupClass()}>
  <button class=${buttonClass({ variant: 'outline' })}>Button 1</button>
  <button class=${buttonClass({ variant: 'outline' })}>Button 2</button>
</div>
```

## Composition

Use the following composition to build a button group:

```text
buttonGroupClass()
├── a button or an input
├── buttonGroupSeparatorClass()
└── buttonGroupTextClass()
```

## Accessibility

- Put `role="group"` on the element that carries `buttonGroupClass()`. The helper returns classes only, so the role is yours to write.
- Use `Tab` to navigate between the buttons in the group.
- Use `aria-label` or `aria-labelledby` to label the button group.

```ts
<div role="group" aria-label="Button group" class=${buttonGroupClass()}>
  <button class=${buttonClass({ variant: 'outline' })}>Button 1</button>
  <button class=${buttonClass({ variant: 'outline' })}>Button 2</button>
</div>
```

## ButtonGroup vs ToggleGroup

- Use a button group when you want to group buttons that perform an action.
- Use the [Toggle Group](https://webjs.dev/ui/docs/components/toggle-group) when you want to group buttons that toggle a state.

## Orientation

Pass the `orientation` option to `buttonGroupClass()`, and set the matching `data-orientation`, to change the button group layout.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import { buttonGroupClass } from '#components/ui/button-group.ts';
import { MinusIcon, PlusIcon } from '#lib/ui/lucide.ts';

export default function ButtonGroupOrientation() {
  return html`
    <div role="group" data-slot="button-group" data-orientation="vertical" aria-label="Media controls" class=${cn(buttonGroupClass({ orientation: 'vertical' }), 'h-fit')}>
      <button type="button" data-slot="button" data-variant="outline" data-size="icon" aria-label="Increase" class=${buttonClass({ variant: 'outline', size: 'icon' })}>
        ${PlusIcon()}
      </button>
      <button type="button" data-slot="button" data-variant="outline" data-size="icon" aria-label="Decrease" class=${buttonClass({ variant: 'outline', size: 'icon' })}>
        ${MinusIcon()}
      </button>
    </div>
  `;
}
```

## Size

Control the size of buttons using the `size` option of `buttonClass()` on individual buttons.

```ts
import { html } from '@webjsdev/core';
import { buttonClass } from '#components/ui/button.ts';
import { buttonGroupClass } from '#components/ui/button-group.ts';
import { PlusIcon } from '#lib/ui/lucide.ts';

export default function ButtonGroupSize() {
  return html`
    <div class="flex flex-col items-start gap-8">
      <div role="group" data-slot="button-group" data-orientation="horizontal" class=${buttonGroupClass()}>
        <button type="button" data-slot="button" data-variant="outline" data-size="sm" class=${buttonClass({ variant: 'outline', size: 'sm' })}>Small</button>
        <button type="button" data-slot="button" data-variant="outline" data-size="sm" class=${buttonClass({ variant: 'outline', size: 'sm' })}>Button</button>
        <button type="button" data-slot="button" data-variant="outline" data-size="sm" class=${buttonClass({ variant: 'outline', size: 'sm' })}>Group</button>
        <button type="button" data-slot="button" data-variant="outline" data-size="icon-sm" aria-label="Add" class=${buttonClass({ variant: 'outline', size: 'icon-sm' })}>
          ${PlusIcon()}
        </button>
      </div>
      <div role="group" data-slot="button-group" data-orientation="horizontal" class=${buttonGroupClass()}>
        <button type="button" data-slot="button" data-variant="outline" data-size="default" class=${buttonClass({ variant: 'outline' })}>Default</button>
        <button type="button" data-slot="button" data-variant="outline" data-size="default" class=${buttonClass({ variant: 'outline' })}>Button</button>
        <button type="button" data-slot="button" data-variant="outline" data-size="default" class=${buttonClass({ variant: 'outline' })}>Group</button>
        <button type="button" data-slot="button" data-variant="outline" data-size="icon" aria-label="Add" class=${buttonClass({ variant: 'outline', size: 'icon' })}>
          ${PlusIcon()}
        </button>
      </div>
      <div role="group" data-slot="button-group" data-orientation="horizontal" class=${buttonGroupClass()}>
        <button type="button" data-slot="button" data-variant="outline" data-size="lg" class=${buttonClass({ variant: 'outline', size: 'lg' })}>Large</button>
        <button type="button" data-slot="button" data-variant="outline" data-size="lg" class=${buttonClass({ variant: 'outline', size: 'lg' })}>Button</button>
        <button type="button" data-slot="button" data-variant="outline" data-size="lg" class=${buttonClass({ variant: 'outline', size: 'lg' })}>Group</button>
        <button type="button" data-slot="button" data-variant="outline" data-size="icon-lg" aria-label="Add" class=${buttonClass({ variant: 'outline', size: 'icon-lg' })}>
          ${PlusIcon()}
        </button>
      </div>
    </div>
  `;
}
```

## Nested

Nest button groups to create button groups with spacing.

```ts
import { html } from '@webjsdev/core';
import { buttonClass } from '#components/ui/button.ts';
import { buttonGroupClass } from '#components/ui/button-group.ts';
import {
  inputGroupClass, inputGroupAddonClass, inputGroupInputClass,
} from '#components/ui/input-group.ts';
import { AudioLinesIcon, PlusIcon } from '#lib/ui/lucide.ts';

export default function ButtonGroupNested() {
  return html`
    <div role="group" data-slot="button-group" data-orientation="horizontal" class=${buttonGroupClass()}>
      <div role="group" data-slot="button-group" data-orientation="horizontal" class=${buttonGroupClass()}>
        <button type="button" data-slot="button" data-variant="outline" data-size="icon" aria-label="Add" class=${buttonClass({ variant: 'outline', size: 'icon' })}>
          ${PlusIcon()}
        </button>
      </div>
      <div role="group" data-slot="button-group" data-orientation="horizontal" class=${buttonGroupClass()}>
        <div data-slot="input-group" role="group" class=${inputGroupClass()}>
          <input data-slot="input-group-control" type="text" placeholder="Send a message..." aria-label="Message" class=${inputGroupInputClass()}>
          <div data-slot="input-group-addon" data-align="inline-end" class=${inputGroupAddonClass({ align: 'inline-end' })}>
            <ui-tooltip>
              <ui-tooltip-trigger>
                ${AudioLinesIcon()}
              </ui-tooltip-trigger>
              <ui-tooltip-content>Voice Mode</ui-tooltip-content>
            </ui-tooltip>
          </div>
        </div>
      </div>
    </div>
  `;
}
```

## Separator

`buttonGroupSeparatorClass()` visually divides buttons within a group. Compose it with the separator helper, `cn(separatorClass({ orientation: 'vertical' }), buttonGroupSeparatorClass())`.

Buttons with variant `outline` do not need a separator since they have a border. For other variants, a separator is recommended to improve the visual hierarchy.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import { buttonGroupClass, buttonGroupSeparatorClass } from '#components/ui/button-group.ts';
import { separatorClass } from '#components/ui/separator.ts';

export default function ButtonGroupSeparatorDemo() {
  return html`
    <div role="group" data-slot="button-group" data-orientation="horizontal" class=${buttonGroupClass()}>
      <button type="button" data-slot="button" data-variant="secondary" data-size="sm" class=${buttonClass({ variant: 'secondary', size: 'sm' })}>Copy</button>
      <div role="none" data-slot="button-group-separator" data-orientation="vertical" class=${cn(separatorClass({ orientation: 'vertical' }), buttonGroupSeparatorClass())}></div>
      <button type="button" data-slot="button" data-variant="secondary" data-size="sm" class=${buttonClass({ variant: 'secondary', size: 'sm' })}>Paste</button>
    </div>
  `;
}
```

## Split

Create a split button group by adding two buttons separated by a separator.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import { buttonGroupClass, buttonGroupSeparatorClass } from '#components/ui/button-group.ts';
import { separatorClass } from '#components/ui/separator.ts';
import { IconPlus } from '#lib/ui/tabler.ts';

export default function ButtonGroupSplit() {
  return html`
    <div role="group" data-slot="button-group" data-orientation="horizontal" class=${buttonGroupClass()}>
      <button type="button" data-slot="button" data-variant="secondary" data-size="default" class=${buttonClass({ variant: 'secondary' })}>Button</button>
      <div role="none" data-slot="button-group-separator" data-orientation="vertical" class=${cn(separatorClass({ orientation: 'vertical' }), buttonGroupSeparatorClass())}></div>
      <button type="button" data-slot="button" data-variant="secondary" data-size="icon" aria-label="Add" class=${buttonClass({ variant: 'secondary', size: 'icon' })}>
        ${IconPlus()}
      </button>
    </div>
  `;
}
```

## Input

Wrap an [Input](https://webjs.dev/ui/docs/components/input) with buttons.

```ts
import { html } from '@webjsdev/core';
import { buttonClass } from '#components/ui/button.ts';
import { buttonGroupClass } from '#components/ui/button-group.ts';
import { inputClass } from '#components/ui/input.ts';
import { SearchIcon } from '#lib/ui/lucide.ts';

export default function ButtonGroupInput() {
  return html`
    <div role="group" data-slot="button-group" data-orientation="horizontal" class=${buttonGroupClass()}>
      <input data-slot="input" type="text" placeholder="Search..." aria-label="Search" class=${inputClass()}>
      <button type="button" data-slot="button" data-variant="outline" data-size="default" aria-label="Search" class=${buttonClass({ variant: 'outline' })}>
        ${SearchIcon()}
      </button>
    </div>
  `;
}
```

## Input Group

Wrap an [Input Group](https://webjs.dev/ui/docs/components/input-group) to create complex input layouts.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import { buttonGroupClass } from '#components/ui/button-group.ts';
import {
  inputGroupClass, inputGroupAddonClass, inputGroupButtonClass, inputGroupInputClass,
} from '#components/ui/input-group.ts';
import { AudioLinesIcon, PlusIcon } from '#lib/ui/lucide.ts';

export default function ButtonGroupInputGroup() {
  return html`
    <div role="group" data-slot="button-group" data-orientation="horizontal" class=${cn(buttonGroupClass(), '[--radius:9999rem]')}>
      <div role="group" data-slot="button-group" data-orientation="horizontal" class=${buttonGroupClass()}>
        <button type="button" data-slot="button" data-variant="outline" data-size="icon" aria-label="Add" class=${buttonClass({ variant: 'outline', size: 'icon' })}>
          ${PlusIcon()}
        </button>
      </div>
      <div role="group" data-slot="button-group" data-orientation="horizontal" class=${buttonGroupClass()}>
        <div data-slot="input-group" role="group" class=${inputGroupClass()}>
          <input data-slot="input-group-control" type="text" placeholder="Send a message..." aria-label="Message" class=${inputGroupInputClass()}>
          <div data-slot="input-group-addon" data-align="inline-end" class=${inputGroupAddonClass({ align: 'inline-end' })}>
            <ui-tooltip>
              <ui-tooltip-trigger>
                <button type="button" data-slot="button" data-size="icon-xs" data-active="false" aria-pressed="false" aria-label="Voice Mode" class=${cn(inputGroupButtonClass({ size: 'icon-xs' }), 'data-[active=true]:bg-orange-100 data-[active=true]:text-orange-700 dark:data-[active=true]:bg-orange-800 dark:data-[active=true]:text-orange-100')}>
                  ${AudioLinesIcon()}
                </button>
              </ui-tooltip-trigger>
              <ui-tooltip-content>Voice Mode</ui-tooltip-content>
            </ui-tooltip>
          </div>
        </div>
      </div>
    </div>
  `;
}
```

## Dropdown Menu

Create a split button group with a [Dropdown Menu](https://webjs.dev/ui/docs/components/dropdown-menu). The menu names its trigger with `trigger="<id>"`, so the button stays a direct child of the group.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import { buttonGroupClass } from '#components/ui/button-group.ts';
import {
  AlertTriangleIcon, CheckIcon, ChevronDownIcon, CopyIcon, ShareIcon, TrashIcon,
  UserRoundXIcon, VolumeOffIcon,
} from '#lib/ui/lucide.ts';

export default function ButtonGroupDropdown() {
  return html`
    <div role="group" data-slot="button-group" data-orientation="horizontal" class=${buttonGroupClass()}>
      <button type="button" data-slot="button" data-variant="outline" data-size="default" class=${buttonClass({ variant: 'outline' })}>Follow</button>
      <button type="button" id="button-group-dropdown-trigger" data-slot="button" data-variant="outline" data-size="default" aria-label="More options" class=${cn(buttonClass({ variant: 'outline' }), 'pl-2!')}>
        ${ChevronDownIcon()}
      </button>
    </div>
    <ui-dropdown-menu trigger="button-group-dropdown-trigger" class="absolute">
      <ui-dropdown-menu-content align="end" class="w-44">
        <ui-dropdown-menu-group>
          <ui-dropdown-menu-item>
            ${VolumeOffIcon()}
            Mute Conversation
          </ui-dropdown-menu-item>
          <ui-dropdown-menu-item>
            ${CheckIcon()}
            Mark as Read
          </ui-dropdown-menu-item>
          <ui-dropdown-menu-item>
            ${AlertTriangleIcon()}
            Report Conversation
          </ui-dropdown-menu-item>
          <ui-dropdown-menu-item>
            ${UserRoundXIcon()}
            Block User
          </ui-dropdown-menu-item>
          <ui-dropdown-menu-item>
            ${ShareIcon()}
            Share Conversation
          </ui-dropdown-menu-item>
          <ui-dropdown-menu-item>
            ${CopyIcon()}
            Copy Conversation
          </ui-dropdown-menu-item>
        </ui-dropdown-menu-group>
        <ui-dropdown-menu-separator></ui-dropdown-menu-separator>
        <ui-dropdown-menu-group>
          <ui-dropdown-menu-item variant="destructive">
            ${TrashIcon()}
            Delete Conversation
          </ui-dropdown-menu-item>
        </ui-dropdown-menu-group>
      </ui-dropdown-menu-content>
    </ui-dropdown-menu>
  `;
}
```

## Select

Pair with a [Select](https://webjs.dev/ui/docs/components/select).

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import { buttonGroupClass } from '#components/ui/button-group.ts';
import { inputClass } from '#components/ui/input.ts';
import { selectTriggerClass } from '#components/ui/select.ts';
import { ArrowRightIcon } from '#lib/ui/lucide.ts';

const CURRENCIES = [
  { value: '$', label: 'US Dollar' },
  { value: '€', label: 'Euro' },
  { value: '£', label: 'British Pound' },
];

export default function ButtonGroupSelect() {
  return html`
    <div role="group" data-slot="button-group" data-orientation="horizontal" class=${buttonGroupClass()}>
      <div role="group" data-slot="button-group" data-orientation="horizontal" class=${buttonGroupClass()}>
        <ui-select position="popper">
          <select name="currency" aria-label="Currency" class=${cn(selectTriggerClass(), 'rounded-e-none font-mono')}>
            ${CURRENCIES.map((currency) => html`
              <option value=${currency.value} ?selected=${currency.value === '$'}>${currency.value} ${currency.label}</option>
            `)}
          </select>
        </ui-select>
        <input data-slot="input" type="text" placeholder="10.00" pattern="[0-9]*" aria-label="Amount" class=${inputClass()}>
      </div>
      <div role="group" data-slot="button-group" data-orientation="horizontal" class=${buttonGroupClass()}>
        <button type="button" data-slot="button" data-variant="outline" data-size="icon" aria-label="Send" class=${buttonClass({ variant: 'outline', size: 'icon' })}>
          ${ArrowRightIcon()}
        </button>
      </div>
    </div>
  `;
}
```

## Popover

Use with a [Popover](https://webjs.dev/ui/docs/components/popover).

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import { buttonGroupClass } from '#components/ui/button-group.ts';
import { fieldClass, fieldLabelClass, fieldDescriptionClass } from '#components/ui/field.ts';
import {
  popoverContentClass, popoverHeaderClass, popoverTitleClass, popoverDescriptionClass,
} from '#components/ui/popover.ts';
import { textareaClass } from '#components/ui/textarea.ts';
import { BotIcon, ChevronDownIcon } from '#lib/ui/lucide.ts';

export default function ButtonGroupPopover() {
  return html`
    <div role="group" data-slot="button-group" data-orientation="horizontal" class=${buttonGroupClass()}>
      <button type="button" data-slot="button" data-variant="outline" data-size="default" class=${buttonClass({ variant: 'outline' })}>
        ${BotIcon()} Copilot
      </button>
      <button type="button" popovertarget="button-group-popover" aria-haspopup="dialog" aria-expanded="false" aria-label="Open Popover" data-slot="button" data-variant="outline" data-size="icon" class=${buttonClass({ variant: 'outline', size: 'icon' })}>
        ${ChevronDownIcon()}
      </button>
    </div>
    <div id="button-group-popover" popover role="dialog" aria-labelledby="button-group-popover-title" aria-describedby="button-group-popover-description" data-slot="popover-content" data-side="bottom" data-align="end" class=${cn(popoverContentClass({ side: 'bottom', align: 'end' }), 'rounded-xl text-sm')}>
      <div data-slot="popover-header" class=${popoverHeaderClass()}>
        <h3 id="button-group-popover-title" data-slot="popover-title" class=${popoverTitleClass()}>Start a new task with Copilot</h3>
        <p id="button-group-popover-description" data-slot="popover-description" class=${popoverDescriptionClass()}>
          Describe your task in natural language.
        </p>
      </div>
      <div role="group" data-slot="field" data-orientation="vertical" class=${fieldClass()}>
        <label data-slot="field-label" for="button-group-popover-task" class=${cn(fieldLabelClass(), 'sr-only')}>Task Description</label>
        <textarea data-slot="textarea" id="button-group-popover-task" placeholder="I need to..." class=${cn(textareaClass(), 'resize-none')}></textarea>
        <p data-slot="field-description" class=${fieldDescriptionClass()}>
          Copilot will open a pull request for review.
        </p>
      </div>
    </div>
  `;
}
```

## RTL

To enable RTL support, see the [RTL configuration guide](https://webjs.dev/ui/docs/rtl).

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import { buttonGroupClass } from '#components/ui/button-group.ts';
import {
  ArchiveIcon, ArrowLeftIcon, CalendarPlusIcon, ClockIcon, ListFilterIcon,
  MailCheckIcon, MoreHorizontalIcon, TagIcon, Trash2Icon,
} from '#lib/ui/lucide.ts';

const translations = {
  en: {
    dir: 'ltr',
    values: {
      archive: 'Archive',
      report: 'Report',
      snooze: 'Snooze',
      markAsRead: 'Mark as Read',
      addToCalendar: 'Add to Calendar',
      addToList: 'Add to List',
      labelAs: 'Label As...',
      personal: 'Personal',
      work: 'Work',
      other: 'Other',
      trash: 'Trash',
    },
  },
  ar: {
    dir: 'rtl',
    values: {
      archive: 'أرشفة',
      report: 'تقرير',
      snooze: 'تأجيل',
      markAsRead: 'وضع علامة كمقروء',
      addToCalendar: 'إضافة إلى التقويم',
      addToList: 'إضافة إلى القائمة',
      labelAs: 'تصنيف كـ...',
      personal: 'شخصي',
      work: 'عمل',
      other: 'آخر',
      trash: 'سلة المهملات',
    },
  },
  he: {
    dir: 'rtl',
    values: {
      archive: 'ארכיון',
      report: 'דוח',
      snooze: 'דחה',
      markAsRead: 'סמן כנקרא',
      addToCalendar: 'הוסף ליומן',
      addToList: 'הוסף לרשימה',
      labelAs: 'תייג כ...',
      personal: 'אישי',
      work: 'עבודה',
      other: 'אחר',
      trash: 'פח',
    },
  },
};

// The provider is the dir attribute: the group flattens its corners by
// logical side, and the menu opens in the top layer but stays in the
// document, so both inherit dir="rtl" from the wrapper.
export default function ButtonGroupRtl() {
  const lang = 'ar';
  const { dir, values: t } = translations[lang];

  return html`
    <div dir=${dir} lang=${lang}>
      <div role="group" data-slot="button-group" data-orientation="horizontal" class=${buttonGroupClass()}>
        <div role="group" data-slot="button-group" data-orientation="horizontal" class=${cn(buttonGroupClass(), 'hidden sm:flex')}>
          <button type="button" data-slot="button" data-variant="outline" data-size="icon" aria-label="Go Back" class=${buttonClass({ variant: 'outline', size: 'icon' })}>
            ${ArrowLeftIcon('rtl:rotate-180')}
          </button>
        </div>
        <div role="group" data-slot="button-group" data-orientation="horizontal" class=${buttonGroupClass()}>
          <button type="button" data-slot="button" data-variant="outline" data-size="default" class=${buttonClass({ variant: 'outline' })}>${t.archive}</button>
          <button type="button" data-slot="button" data-variant="outline" data-size="default" class=${buttonClass({ variant: 'outline' })}>${t.report}</button>
        </div>
        <div role="group" data-slot="button-group" data-orientation="horizontal" class=${buttonGroupClass()}>
          <button type="button" data-slot="button" data-variant="outline" data-size="default" class=${buttonClass({ variant: 'outline' })}>${t.snooze}</button>
          <button type="button" id="button-group-rtl-more" data-slot="button" data-variant="outline" data-size="icon" aria-label="More Options" class=${buttonClass({ variant: 'outline', size: 'icon' })}>
            ${MoreHorizontalIcon()}
          </button>
        </div>
      </div>
      <ui-dropdown-menu trigger="button-group-rtl-more" class="absolute">
        <ui-dropdown-menu-content align="end" class="w-40">
          <ui-dropdown-menu-group>
            <ui-dropdown-menu-item>
              ${MailCheckIcon()}
              ${t.markAsRead}
            </ui-dropdown-menu-item>
            <ui-dropdown-menu-item>
              ${ArchiveIcon()}
              ${t.archive}
            </ui-dropdown-menu-item>
          </ui-dropdown-menu-group>
          <ui-dropdown-menu-separator></ui-dropdown-menu-separator>
          <ui-dropdown-menu-group>
            <ui-dropdown-menu-item>
              ${ClockIcon()}
              ${t.snooze}
            </ui-dropdown-menu-item>
            <ui-dropdown-menu-item>
              ${CalendarPlusIcon()}
              ${t.addToCalendar}
            </ui-dropdown-menu-item>
            <ui-dropdown-menu-item>
              ${ListFilterIcon()}
              ${t.addToList}
            </ui-dropdown-menu-item>
            <ui-dropdown-menu-sub>
              <ui-dropdown-menu-sub-trigger>
                ${TagIcon()}
                ${t.labelAs}
              </ui-dropdown-menu-sub-trigger>
              <ui-dropdown-menu-sub-content>
                <ui-dropdown-menu-group aria-label=${t.labelAs}>
                  <ui-dropdown-menu-item type="radio" value="personal" checked>${t.personal}</ui-dropdown-menu-item>
                  <ui-dropdown-menu-item type="radio" value="work">${t.work}</ui-dropdown-menu-item>
                  <ui-dropdown-menu-item type="radio" value="other">${t.other}</ui-dropdown-menu-item>
                </ui-dropdown-menu-group>
              </ui-dropdown-menu-sub-content>
            </ui-dropdown-menu-sub>
          </ui-dropdown-menu-group>
          <ui-dropdown-menu-separator></ui-dropdown-menu-separator>
          <ui-dropdown-menu-group>
            <ui-dropdown-menu-item variant="destructive">
              ${Trash2Icon()}
              ${t.trash}
            </ui-dropdown-menu-item>
          </ui-dropdown-menu-group>
        </ui-dropdown-menu-content>
      </ui-dropdown-menu>
    </div>
  `;
}
```

## API Reference

### buttonGroupClass

`buttonGroupClass()` returns the classes for a container that groups related buttons together with consistent styling. Put them on an element with `role="group"`, `data-slot="button-group"` and a `data-orientation` matching the option. `buttonGroupVariants()` is an alias of `buttonGroupClass()` that also merges a `className`.

| Option | Type | Default |
| --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |

```ts
<div role="group" data-slot="button-group" data-orientation="horizontal" class=${buttonGroupClass()}>
  <button class=${buttonClass()}>Button 1</button>
  <button class=${buttonClass()}>Button 2</button>
</div>
```

Nest multiple button groups to create complex layouts with spacing. See the nested example for more details.

```ts
<div role="group" data-slot="button-group" class=${buttonGroupClass()}>
  <div role="group" data-slot="button-group" class=${buttonGroupClass()}></div>
  <div role="group" data-slot="button-group" class=${buttonGroupClass()}></div>
</div>
```

### buttonGroupSeparatorClass

`buttonGroupSeparatorClass()` visually divides buttons within a group. It takes no options: compose it with `separatorClass()` and set the orientation on the element with `data-orientation`, which is `"vertical"` for a horizontal group.

| Attribute | Type | Default |
| --- | --- | --- |
| `data-orientation` | `"horizontal" \| "vertical"` | `"vertical"` |

```ts
<div role="group" data-slot="button-group" class=${buttonGroupClass()}>
  <button class=${buttonClass()}>Button 1</button>
  <div
    role="none"
    data-slot="button-group-separator"
    data-orientation="vertical"
    class=${cn(separatorClass({ orientation: 'vertical' }), buttonGroupSeparatorClass())}
  ></div>
  <button class=${buttonClass()}>Button 2</button>
</div>
```

### buttonGroupTextClass

Use this helper to display text within a button group. It takes no options.

```ts
<div role="group" data-slot="button-group" class=${buttonGroupClass()}>
  <div class=${buttonGroupTextClass()}>Text</div>
  <button class=${buttonClass()}>Button</button>
</div>
```

A class helper styles any element, so to render the text as a label, put the classes on a `<label>`.

```ts
import { buttonGroupClass, buttonGroupTextClass } from '#components/ui/button-group.ts';
import { inputClass } from '#components/ui/input.ts';

export function ButtonGroupTextDemo() {
  return html`
    <div role="group" data-slot="button-group" class=${buttonGroupClass()}>
      <label for="name" class=${buttonGroupTextClass()}>Text</label>
      <input id="name" placeholder="Type something here..." class=${inputClass()}>
    </div>
  `;
}
```
