Choice

# Brok UI: Label Selector (`label-selector`)

Selectable chips for single or multiple choice that submit in a normal form with no JavaScript.

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

## Install

```bash
php artisan ui:add label-selector
```

## Usage

```blade
<div class="space-y-6 text-start">
    <div class="space-y-2">
        <p class="text-sm font-medium text-foreground">{{ __('Primary topic') }}</p>
        <x-ui.label-selector name="preview-topic">
            <x-ui.label-selector.item value="design">{{ __('Design') }}</x-ui.label-selector.item>
            <x-ui.label-selector.item value="engineering" checked>{{ __('Engineering') }}</x-ui.label-selector.item>
            <x-ui.label-selector.item value="product">{{ __('Product') }}</x-ui.label-selector.item>
            <x-ui.label-selector.item value="marketing">{{ __('Marketing') }}</x-ui.label-selector.item>
            <x-ui.label-selector.item value="sales">{{ __('Sales') }}</x-ui.label-selector.item>
        </x-ui.label-selector>
    </div>

    <div class="space-y-2">
        <p class="text-sm font-medium text-foreground">{{ __('Interested topics') }}</p>
        <x-ui.label-selector name="preview-topics" multiple>
            <x-ui.label-selector.item value="design" checked>{{ __('Design') }}</x-ui.label-selector.item>
            <x-ui.label-selector.item value="engineering">{{ __('Engineering') }}</x-ui.label-selector.item>
            <x-ui.label-selector.item value="product" checked>{{ __('Product') }}</x-ui.label-selector.item>
            <x-ui.label-selector.item value="marketing">{{ __('Marketing') }}</x-ui.label-selector.item>
            <x-ui.label-selector.item value="sales">{{ __('Sales') }}</x-ui.label-selector.item>
        </x-ui.label-selector>
    </div>
</div>
```

## Props

- `name` (mixed, default `required`) — Declared by @props in the shipped Blade source.
- `value` (mixed, default `null`) — Submitted value for this chip's hidden radio or checkbox input.
- `multiple` (bool, default `false`) — Declared by @props in the shipped Blade source.
- `options` (array, default `[]`) — Declared by @props in the shipped Blade source.
- `disabled` (false|true, default `false`) — Documented catalog control used by the preview workbench.
- `checked` (bool, default `false`) — Declared by @props in the registry Blade source.

## Use when

- Use for a small set of mutually exclusive options that users should compare visibly before choosing.
- Offering a compact set of chip-style choices, such as tags or categories, that must submit in a plain form.
- Letting users toggle single or multiple selections without any JavaScript on the server side.

## Avoid when

- Do not hide a small option set in a dropdown when recognition and comparison matter.
- Presenting options with a title, description, or icon; use choicebox instead.
- Building a long list of options; a select or combobox scales better.

## Anti-patterns

- Hiding a small comparable set in a dropdown

## Rules

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

@props([
    'name',
    'value' => null,
    'multiple' => false,
    'options' => [],
])

{{--
    Selectable chips/tags. Single-choice uses native <input type="radio">;
    multi-choice (`:multiple`) uses native <input type="checkbox">. Each input
    is visually hidden (peer) inside a styled <label> chip, so the group submits
    in a normal <form> with NO JavaScript and selection is shown purely via CSS
    (peer-checked). Chips inherit `name`/`multiple` via @aware; the default
    selection is set from `value` on the `:options` path, or by marking composed
    chips with `checked`. When `multiple`, chips submit as an array via
    `name="{name}[]"`.
--}}
<div
    role="group"
    data-slot="label-selector"
    {{ $attributes->merge(['class' => 'flex flex-wrap gap-2']) }}
>
    @if (! empty($options))
        @foreach ($options as $optionValue => $optionLabel)
            <x-ui.label-selector.item
                :value="$optionValue"
                :checked="$multiple
                    ? in_array((string) $optionValue, array_map('strval', (array) $value), true)
                    : ($value !== null && (string) $optionValue === (string) $value)"
            >{{ __($optionLabel) }}</x-ui.label-selector.item>
        @endforeach
    @else
        {{ $slot }}
    @endif
</div>

@aware([
    'name' => null,
    'multiple' => false,
])

@props([
    'value',
    'disabled' => false,
    'checked' => false,
])

@php
    // The native input is the "peer": visually hidden but focusable, so we get
    // form submission and :checked semantics for free. Chip styling is driven
    // entirely off peer state via CSS (peer-checked / peer-focus-visible).
    //
    // The input type/name come from the group's `multiple` flag (inherited via
    // @aware). Default selection is server-rendered via the `checked` prop: the
    // <x-ui.label-selector :options> path sets it from the group `value`;
    // @aware cannot carry the group value into a chip because the chip's own
    // `value` attribute shadows it (documented caveat), so hand-composed chips
    // mark their defaults with `checked`.
    $isMultiple = (bool) $multiple;

    // When multiple, submit as an array so the server receives all selections.
    $inputName = $name === null ? null : ($isMultiple ? $name.'[]' : $name);

    // The styled element is the <label> that WRAPS the input, so we key off
    // :has(:checked) / :has(:focus-visible) on the label — peer-* only reaches
    // later siblings, never the input's own parent.
    $chip = 'inline-flex items-center gap-2 rounded-full border border-border bg-muted px-3 py-1 '
        .'text-sm font-medium text-foreground cursor-pointer transition-colors motion-reduce:transition-none '
        .'has-[:checked]:bg-primary has-[:checked]:text-primary-foreground has-[:checked]:border-primary '
        .'has-[:focus-visible]:ring-2 has-[:focus-visible]:ring-ring has-[:focus-visible]:ring-offset-2 has-[:focus-visible]:ring-offset-background';

    $disabledClasses = $disabled ? ' opacity-50 cursor-not-allowed' : '';
@endphp

<label
    data-slot="label-selector-item"
    @if ($disabled) aria-disabled="true" @endif
    {{ $attributes->merge(['class' => trim($chip.$disabledClasses)]) }}
>
    <input
        type="{{ $isMultiple ? 'checkbox' : 'radio' }}"
        class="peer sr-only"
        name="{{ $inputName }}"
        value="{{ $value }}"
        @checked($checked)
        @disabled($disabled)
    />
    {{ $slot }}
</label>