Checkbox

# Brok UI: Checkbox (`checkbox`)

Native checkbox with sm/md/lg sizes, indeterminate, invalid, disabled, dark, and RTL support. Optional animated variant with a spring-drawn SVG tick and strike-through label (reduced-motion safe).

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

## Install

```bash
php artisan ui:add checkbox
```

## Usage

```blade
<label class="flex items-center gap-2 text-sm text-foreground">
    <x-ui.checkbox id="preview-checkbox" checked />
    {{ __('Accept terms and conditions') }}
</label>
```

## Props

- `size` (md|sm|lg|default, default `md`) — Box dimension; sm and md render the same size, lg is larger.
- `indeterminate` (bool, default `false`) — Renders the native mixed state via aria-checked and JS, for a partially checked group.
- `invalid` (bool, default `false`) — Switches the accent to destructive and sets aria-invalid; also inferred from a wrapping field's validation errors.
- `disabled` (bool, default `false`) — Disables interaction and dims the control.
- `checked` (bool, default `false`) — Initial checked state.

## Use when

- Use for independent selections that can coexist.
- Capturing an independent true/false or a tri-state selection inside a form.
- Letting the user pick zero or more options from a related set.

## Avoid when

- Do not use for mutually exclusive choices; radio is clearer.
- Toggling a setting that applies immediately; use switch instead.
- Choosing exactly one option from a set; use radio.

## Anti-patterns

- Using checkboxes for mutually exclusive answers

## Rules

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

{{-- A wrapping <x-ui.field name="…"> shares its name down via @aware, so the
     checkbox self-wires id + aria-invalid/aria-describedby off the shared $errors
     bag (and its <label for> resolves). With no field ancestor and no own name it
     stays inert — fully backward-compatible. Checked-state restoration is left to
     the consumer (@checked / wire:model), the idiomatic Laravel/Livewire approach. --}}
@aware([
    'name' => null,
    'htmlName' => null,
    'required' => false,
])

@props([
    'size' => 'md',
    'indeterminate' => false,
    'invalid' => false,
    'disabled' => false,
    // Opt-in: a custom control whose SVG tick springs in on check (the draw +
    // optional label strike live in ui.css, keyed on [data-variant="animated"]).
    // Default (false) keeps the bare, native accent-tinted checkbox unchanged.
    'animated' => false,
    // Optional inline label rendered beside the animated box.
    'label' => null,
    // Strike the label through (and mute it) when checked. Only when `animated`.
    'lineThrough' => true,
    // Fill of the checked box. neutral (default) uses the foreground colour,
    // so a product that keeps primary for its one main action and for focus is
    // not diluted; primary uses the brand primary.
    'tone' => 'neutral',
])

@php
    // Full class strings per size so Tailwind's JIT can see every utility —
    // never splice the dimension into an arbitrary class.
    $sizes = [
        'sm' => 'size-4',
        'md' => 'size-4',
        'lg' => 'size-5',
    ];
    // 'default' is shadcn's canonical size token; alias it to md (additive).
    $size = $size === 'default' ? 'md' : (isset($sizes[$size]) ? $size : 'md');

    // Checked colour per tone: the native accent, the animated box and its tick.
    $tones = [
        'neutral' => ['accent' => 'accent-foreground', 'box' => 'peer-checked:border-foreground peer-checked:bg-foreground', 'tick' => 'text-background'],
        'primary' => ['accent' => 'accent-primary', 'box' => 'peer-checked:border-primary peer-checked:bg-primary', 'tick' => 'text-primary-foreground'],
    ];
    $tone = isset($tones[$tone]) ? $tone : 'neutral';

    // Laravel-native wiring (mirrors input). @aware leaves $name undefined with no
    // wrapping field, so normalise it; an explicit name attribute also counts.
    $awareName = $name ?? null;
    $awareHtmlName = $htmlName ?? null;
    $fieldName = $awareName ?? $attributes->get('name');
    $resolvedHtmlName = $awareName
        ? ($awareHtmlName ?? collect(explode('.', $awareName))->reduce(
            fn ($carry, $segment, $index) => $index === 0 ? $segment : $carry.'['.$segment.']',
            ''
        ))
        : $attributes->get('name');
    $bag = ($errors ?? null) instanceof \Illuminate\Support\ViewErrorBag ? $errors : null;
    $hasBagError = $bag && filled($fieldName) && $bag->has($fieldName);
    $isInvalid = $invalid || $hasBagError;
    // Reference the field's error region only when inheriting AND there is an error.
    $describedBy = (filled($awareName) && $hasBagError) ? $fieldName.'-error' : null;
    // A named control needs a stable id so the field's <label for> targets it.
    $resolvedId = $attributes->get('id', filled($fieldName) ? $fieldName : null);
    $isRequired = (bool) ($required ?? false) || $attributes->has('required');
@endphp

@if ($animated)
    {{-- Animated variant: a real (sr-only) checkbox drives a custom box + a
         spring-drawn SVG tick. The native input stays the source of truth for
         state, keyboard and form submission; the label wraps it so the whole
         row is clickable. Box fill/border/focus-ring are peer-* token utilities;
         the tick draw + label strike are handled in ui.css (a sibling-descendant
         the peer combinator can't reach). Colour is token-only throughout.
         The box's invisible ::before widens the pointer target to 24x24. --}}
    <label
        data-slot="checkbox-field"
        @class([
            'inline-flex items-center gap-2 select-none',
            'cursor-pointer' => ! $disabled,
            'cursor-not-allowed opacity-50' => $disabled,
        ])
    >
        <input
            type="checkbox"
            data-slot="checkbox"
            data-variant="animated"
            data-size="{{ $size }}"
            data-tone="{{ $tone }}"
            @if ($lineThrough) data-line-through="true" @endif
            class="peer sr-only"
            @if (filled($resolvedHtmlName)) name="{{ $resolvedHtmlName }}" @endif
            @if (filled($resolvedId)) id="{{ $resolvedId }}" @endif
            @disabled($disabled)
            @required($isRequired)
            @if ($isRequired) aria-required="true" @endif
            @if ($isInvalid) aria-invalid="true" @endif
            @if (filled($describedBy)) aria-describedby="{{ $describedBy }}" @endif
            @if ($indeterminate)
                aria-checked="mixed"
                x-data="{}"
                x-init="$el.indeterminate = true"
            @endif
            {{ $attributes->except(['class', 'name', 'id', 'required', 'aria-required']) }}
        />
        {{-- The input is sr-only, so consumer `class` lands on the visible box
             (matching the default branch, where `class` reaches the control). --}}
        <span
            aria-hidden="true"
            {{ $attributes->only('class')->class([
                'relative grid shrink-0 place-items-center rounded-[0.3rem] border-2 bg-background transition-colors before:absolute before:-inset-1',
                'peer-focus-visible:ring-2 peer-focus-visible:ring-ring peer-focus-visible:ring-offset-2 peer-focus-visible:ring-offset-background',
                $sizes[$size],
                'border-input '.$tones[$tone]['box'] => ! $isInvalid,
                'border-destructive peer-checked:border-destructive peer-checked:bg-destructive' => $isInvalid,
            ]) }}
        >
            <svg
                viewBox="0 0 16 16"
                fill="none"
                stroke="currentColor"
                stroke-width="2.5"
                stroke-linecap="round"
                stroke-linejoin="round"
                @class(['ui-checkbox-anim-check size-full p-0.5', $isInvalid ? 'text-destructive-foreground' : $tones[$tone]['tick']])
            >
                <path d="M3.5 8.5l3 3 6-7" pathlength="1" />
            </svg>
        </span>
        @if (filled($label))
            <span class="ui-checkbox-anim-label text-sm leading-none text-foreground transition-colors">{{ __($label) }}</span>
        @endif
    </label>
@else
    {{-- Default: the native control tinted with the tone's accent (no extra
         border — matching the radio so a checked box doesn't show a doubled
         outer ring). An invisible ::before reaches 4px past the box on every
         side, so the pointer target is at least 24x24 (WCAG 2.5.8) while the
         drawn box and the layout stay 16px. --}}
    @php
        // `relative` anchors the hit area unless the caller positions the box itself.
        $positioned = preg_match('/(^|\s)(absolute|fixed|sticky)(\s|$)/', (string) $attributes->get('class')) === 1;
        $base = $sizes[$size].($positioned ? '' : ' relative').' shrink-0 cursor-pointer transition-colors before:absolute before:-inset-1 '
            .'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background '
            .'disabled:cursor-not-allowed disabled:opacity-50';
        $state = $isInvalid ? 'accent-destructive' : $tones[$tone]['accent'];
        $classes = trim($base.' '.$state);
    @endphp

    <input
        type="checkbox"
        data-slot="checkbox"
        data-size="{{ $size }}"
        data-tone="{{ $tone }}"
        @if (filled($resolvedHtmlName)) name="{{ $resolvedHtmlName }}" @endif
        @if (filled($resolvedId)) id="{{ $resolvedId }}" @endif
        @disabled($disabled)
        @required($isRequired)
        @if ($isRequired) aria-required="true" @endif
        @if ($isInvalid) aria-invalid="true" @endif
        @if (filled($describedBy)) aria-describedby="{{ $describedBy }}" @endif
        @if ($indeterminate)
            aria-checked="mixed"
            x-data="{}"
            x-init="$el.indeterminate = true"
        @endif
        {{ $attributes->except(['name', 'id', 'required', 'aria-required'])->merge(['class' => $classes]) }}
    />
@endif