Toggle Group

# Brok UI: Toggle Group (`toggle-group`)

A set of two-state buttons with single or multiple selection.

Brok UI is a Laravel Blade component registry. Installed components are plain Blade files the app owns.

## Install

```bash
php artisan ui:add toggle-group
```

## Usage

```blade
<div class="flex flex-col gap-6">
    <x-ui.toggle-group type="single" name="align" value="center" aria-label="{{ __('Text alignment') }}">
        <x-ui.toggle-group.item value="left">{{ __('Left') }}</x-ui.toggle-group.item>
        <x-ui.toggle-group.item value="center">{{ __('Center') }}</x-ui.toggle-group.item>
        <x-ui.toggle-group.item value="right">{{ __('Right') }}</x-ui.toggle-group.item>
    </x-ui.toggle-group>

    <x-ui.toggle-group type="multiple" name="format" aria-label="{{ __('Text formatting') }}">
        <x-ui.toggle-group.item value="bold"><strong>{{ __('Bold') }}</strong></x-ui.toggle-group.item>
        <x-ui.toggle-group.item value="italic"><em>{{ __('Italic') }}</em></x-ui.toggle-group.item>
        <x-ui.toggle-group.item value="underline"><span class="underline">{{ __('Underline') }}</span></x-ui.toggle-group.item>
    </x-ui.toggle-group>
</div>
```

## Props

- `type` (string, default `single`) — Declared by @props in the shipped Blade source.
- `name` (mixed|null, default `null`) — Declared by @props in the shipped Blade source.
- `value` (mixed, default `null`) — This item's value, matched against the group's current selection.
- `variant` (string, default `default`) — Declared by @props in the shipped Blade source.
- `size` (string, default `md`) — Declared by @props in the shipped Blade source.

## Use when

- Use when users choose among a bounded set and space efficiency matters more than always-visible comparison.
- Grouping related two-state buttons, such as text alignment or formatting toggles, that share roving keyboard focus.
- Needing single or multiple selection among a row of pressed/unpressed buttons.

## Avoid when

- Do not use for tiny lists or when users benefit from seeing all options at once.
- Only one standalone toggle is needed; use toggle by itself.
- The choice must submit a single mutually exclusive value with native radio semantics; use radio or radio-tabs.

## Anti-patterns

- Hiding tiny or high-frequency option sets

## Rules

- Use the `<brok:toggle-group>` tag (or `<x-ui.toggle-group>`) in Blade; do not rewrite the component.
- Prefer the documented props and variants over utility-class overrides; when a utility must win, use the `!` important modifier.
- Use semantic design tokens (`bg-primary`, `text-muted-foreground`), never raw colour utilities.
- Keep the `data-slot` attributes; they are the styling and test hooks.

## Links

- Docs: https://brokui.dev/docs/components/toggle-group
- Registry JSON (files, props, contract): https://brokui.dev/r/open/toggle-group.json

@props([
    'type' => 'single',
    'name' => null,
    'value' => null,
    // Item look, read by every toggle-group.item through @aware: toggle's
    // default | outline variants and sm | md | lg control tiers.
    'variant' => 'default',
    'size' => 'md',
])
@php
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');
    $variant = $styles['normalizeVariant']($variant);
    $variant = in_array($variant, ['default', 'outline'], true) ? $variant : 'default';
    $size = in_array($size, ['sm', 'md', 'lg'], true) ? $size : 'md';
@endphp
<div
    x-data="uiToggleGroup({ type: @js($type), value: @js($value) })"
    {{-- Modelable: `x-model` (Alpine) and `wire:model` (Livewire binds through
         the same x-model contract) attach to the root. Inert without either. --}}
    x-modelable="model"
    data-slot="toggle-group"
    data-type="{{ $type }}"
    data-variant="{{ $variant }}"
    data-size="{{ $size }}"
    role="group"
    @keydown="onKey($event)"
    {{ $attributes->merge(['class' => 'inline-flex items-center gap-1 rounded-md']) }}
>
    {{ $slot }}
    @if ($name)
        <input type="hidden" name="{{ $name }}" :value="Array.isArray(value) ? value.join(',') : (value ?? '')" />
    @endif
</div>

@aware([
    'variant' => 'default',
    'size' => 'md',
])

@props(['value'])

@php
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');
    $variant = $styles['normalizeVariant']($variant);
    // One item is a toggle: same recipe, same control tiers, so a group reads
    // as a row of the standalone control. The group owns the pressed state.
    $recipe = $styles['toggle'];
    // The group keeps the accent pressed fill; an older _styles.php carries it in base.
    $pressed = $recipe['tones']['accent'] ?? '';
    $classes = trim($recipe['base'].' '.$pressed.' '.($recipe['variants'][$variant] ?? $recipe['variants']['default']).' '.($recipe['sizes'][$size] ?? $recipe['sizes']['md']));
@endphp

<button
    type="button"
    data-slot="toggle-group-item"
    data-value="{{ $value }}"
    data-variant="{{ $variant }}"
    data-size="{{ $size }}"
    :data-state="isOn(@js($value)) ? 'on' : 'off'"
    :aria-pressed="isOn(@js($value))"
    :tabindex="rovingTabindex($el)"
    @click="toggle(@js($value))"
    {{ $attributes->merge(['class' => $classes]) }}
>{{ $slot }}</button>

/**
 * Toggle group behavior (spec §19 behavior layer).
 *
 * A set of two-state buttons that support "single" (one active value) or
 * "multiple" (an array of active values) selection. Selection state lives on
 * the root so each instance — and any hidden form input — stays independent.
 *
 * Focus uses the roving-tabindex pattern: only one item is in the tab order,
 * and ArrowLeft/Right/Up/Down/Home/End move focus within the group. Horizontal
 * arrows respect the resolved text direction, so they are swapped under RTL.
 *
 * Self-registers on `alpine:init` so import order does not matter — import this
 * file once from your bundle (e.g. resources/js/ui/index.js).
 */
document.addEventListener('alpine:init', () => {
    window.Alpine.data('uiToggleGroup', (config = {}) => ({
        type: config.type ?? 'single',
        value:
            (config.type ?? 'single') === 'multiple'
                ? config.value ?? []
                : config.value ?? null,

        /**
         * Modelable value (`x-modelable="model"` on the root): the pressed value
         * (single) or the array of pressed values (multiple).
         */
        get model() {
            return this.value;
        },
        set model(v) {
            if (this.type === 'multiple') {
                this.value = Array.isArray(v) ? [...v] : (v == null || v === '' ? [] : [v]);
            } else {
                this.value = v == null || v === '' ? null : v;
            }
        },

        isOn(v) {
            return this.type === 'multiple' ? this.value.includes(v) : this.value === v;
        },

        toggle(v) {
            if (this.type === 'multiple') {
                this.value = this.isOn(v)
                    ? this.value.filter((x) => x !== v)
                    : [...this.value, v];
            } else {
                this.value = this.value === v ? null : v;
            }
        },

        /** Items that participate in roving focus (enabled items only). */
        _items() {
            return Array.from(
                this.$el.querySelectorAll('[data-slot="toggle-group-item"]:not(:disabled)')
            );
        },

        /** Only the first "on" item (or the first item) is tabbable. */
        rovingTabindex(el) {
            const items = this._items();
            const active = items.find((i) => i.getAttribute('data-state') === 'on') || items[0];
            return el === active ? 0 : -1;
        },

        /** Roving keyboard navigation, direction-aware for horizontal arrows. */
        onKey(event) {
            const items = this._items();
            const cur = items.indexOf(event.target);
            if (cur === -1) {
                return;
            }

            const rtl = getComputedStyle(this.$el).direction === 'rtl';
            let key = event.key;
            if (rtl) {
                if (key === 'ArrowRight') {
                    key = 'ArrowLeft';
                } else if (key === 'ArrowLeft') {
                    key = 'ArrowRight';
                }
            }

            let next;
            switch (key) {
                case 'ArrowRight':
                case 'ArrowDown':
                    next = (cur + 1) % items.length;
                    break;
                case 'ArrowLeft':
                case 'ArrowUp':
                    next = (cur - 1 + items.length) % items.length;
                    break;
                case 'Home':
                    next = 0;
                    break;
                case 'End':
                    next = items.length - 1;
                    break;
                default:
                    return;
            }

            event.preventDefault();
            items[next].focus();
        },
    }));
});