Switch Field

# Brok UI: Switch Field (`switch-field`)

A preference row: the setting's name as the switch's label, one sentence on what it changes, an optional status badge, and the switch at the end of the row.

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

## Install

```bash
php artisan ui:add switch-field
```

## Usage

```blade
<div class="w-full max-w-md space-y-4">
    <x-ui.switch-field
        :label="__('Require two-factor authentication')"
        :description="__('Enforce 2FA for every member.')"
        name="require_2fa"
        checked
    />
    <x-ui.separator />
    <x-ui.switch-field
        :label="__('Public workspace')"
        :description="__('Allow anyone with the link to view.')"
        name="public_workspace"
    >
        <x-slot:badge><x-ui.badge variant="outline">{{ __('Off') }}</x-ui.badge></x-slot:badge>
    </x-ui.switch-field>
</div>
```

## Props

- `label` (string, default ``) — The setting's name; rendered as the switch's associated label.
- `description` (string|null, default `null`) — One sentence on what the setting changes, under the name.
- `name` (string|null, default `null`) — Form name for the switch input; also seeds the id.
- `id` (string|null, default `null`) — Id shared by the label and the switch; derived from `name` when omitted.
- `value` (string, default `1`) — The value posted when the switch is on.
- `checked` (bool, default `false`) — Initial on/off state.
- `disabled` (bool, default `false`) — Disables the switch; the row keeps its text.
- `size` ('sm'|'md'|'lg', default `md`) — Switch size, forwarded to `switch`.
- `align` ('start'|'center', default `start`) — `start` keeps the switch on the first line of a wrapping description; `center` centres it beside a single-line setting.
- `badge` (slot|null, default `null`) — Slot: a status pill beside the name (a `badge` reading Enabled).

## Use when

- Use for a small set of mutually exclusive options that users should compare visibly before choosing.
- A settings screen lists on/off preferences, each with a name and one sentence on what it changes.
- A card of notification or security options where the whole row should name and toggle the control.

## Avoid when

- Do not hide a small option set in a dropdown when recognition and comparison matter.
- A bare on/off control inline in a sentence; use `switch` with its own label.
- A value saved only on submit with a visible checkmark; use `checkbox`.

## Anti-patterns

- Hiding a small comparable set in a dropdown

## Rules

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

{{--
    Switch Field — the preference row every settings screen repeats: the
    setting's name as the switch's label, one sentence on what it changes,
    and the switch at the end of the row. The label is a real <label for>, so
    the whole text names the control and clicking it toggles the switch.

    `badge` slot: a status pill beside the name ("Enabled"). The default slot
    renders under the description for anything else the row needs to say.
--}}
@props([
    'label' => '',
    'description' => null,
    'name' => null,
    'id' => null,
    'value' => '1',
    'checked' => false,
    'disabled' => false,
    'size' => 'md',
    // start: text top-aligned beside the switch (a description that may wrap);
    // center: a single-line setting.
    'align' => 'start',
    'badge' => null,
])

@php
    $id ??= filled($name) ? 'switch-field-'.\Illuminate\Support\Str::slug((string) $name) : 'switch-field-'.\Illuminate\Support\Str::random(6);
    $align = in_array($align, ['start', 'center'], true) ? $align : 'start';
    $hasBadge = $badge !== null && ! $badge->isEmpty();
@endphp

<div
    data-slot="switch-field"
    data-align="{{ $align }}"
    {{ $attributes->merge(['class' => 'flex justify-between gap-4 '.($align === 'center' ? 'items-center' : 'items-start')]) }}
>
    <div data-slot="switch-field-text" class="min-w-0 flex-1 space-y-0.5">
        <div class="flex min-w-0 flex-wrap items-center gap-2">
            <x-ui.label :for="$id" data-slot="switch-field-label">{{ $label }}</x-ui.label>
            @if ($hasBadge)
                {{ $badge }}
            @endif
        </div>
        @if ($description !== null)
            <p data-slot="switch-field-description" class="text-sm text-muted-foreground">{{ $description }}</p>
        @endif
        @if (trim($slot) !== '')
            <div data-slot="switch-field-content" class="pt-2 text-sm text-muted-foreground">{{ $slot }}</div>
        @endif
    </div>

    <x-ui.switch
        :id="$id"
        :name="$name"
        :value="$value"
        :checked="$checked"
        :disabled="$disabled"
        :size="$size"
        class="shrink-0"
    />
</div>