Toggle

# Brok UI: Toggle (`toggle`)

A two-state button that can be on or off.

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

## Install

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

## Usage

```blade
<div class="flex items-center gap-2">
    <x-ui.toggle aria-label="{{ __('Bold') }}"><strong>B</strong></x-ui.toggle>
    <x-ui.toggle variant="outline" :pressed="true">{{ __('Italic') }}</x-ui.toggle>
</div>
```

## Props

- `pressed` (bool, default `false`) — Initial pressed state, tracked client-side by Alpine.
- `variant` (default|outline, default `default`) — Visual style: default (filled on press) or outline.
- `size` (md|sm|lg, default `md`) — Control height and padding: sm, md, or lg.
- `tone` (neutral|accent, default `neutral`) — Fill of the pressed state: neutral uses the secondary tokens, so a product that keeps its brand colour for the one primary action and focus is not diluted; accent restores the accent fill of 1.2.

## Use when

- Use for immediate state changes that are obvious and reversible.
- Standalone toolbar actions with an on/off state, such as bold or italic in a text toolbar.
- Needing a button-shaped control that tracks pressed state client-side.

## Avoid when

- Do not use for choices that need explanation, confirmation, or a later Save step.
- Grouping several mutually exclusive toggles together; use toggle-group instead.
- Submitting a boolean value in a plain HTML form; use checkbox or switch.

## Anti-patterns

- Using a switch when Save is required
- Using a switch for irreversible actions

## Rules

- Use the `<brok:toggle>` tag (or `<x-ui.toggle>`) 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
- Registry JSON (files, props, contract): https://brokui.dev/r/open/toggle.json

@props([
    'pressed' => false,
    'variant' => 'default',
    'size' => 'md',
    // neutral (default): the pressed fill uses the secondary tokens; accent:
    // the accent fill of 1.x.
    'tone' => 'neutral',
])
@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';
    $recipe = $styles['toggle'];
    // The fallbacks keep an older _styles.php (accent in base, no tones) working.
    $accent = 'data-[state=on]:bg-accent data-[state=on]:text-accent-foreground';
    $tones = ($recipe['tones'] ?? []) + ['neutral' => 'data-[state=on]:bg-secondary data-[state=on]:text-secondary-foreground', 'accent' => $accent];
    $tone = isset($tones[$tone]) ? $tone : 'neutral';
    $base = trim(str_replace($accent, '', $recipe['base']));
    $classes = trim($base.' '.$tones[$tone].' '.($recipe['variants'][$variant] ?? $recipe['variants']['default']).' '.($recipe['sizes'][$size] ?? $recipe['sizes']['md']));
@endphp
<button
    type="button"
    x-data="{ pressed: @js((bool) $pressed) }"
    data-slot="toggle"
    data-variant="{{ $variant }}"
    data-size="{{ $size }}"
    data-tone="{{ $tone }}"
    :data-state="pressed ? 'on' : 'off'"
    :aria-pressed="pressed"
    @click="pressed = !pressed"
    {{ $attributes->merge(['class' => $classes]) }}
>{{ $slot }}</button>