Checkbox

A form control for binary choices or multi-select lists. Supports checked, unchecked, and indeterminate states with full keyboard and screen-reader support.

Basic Usage

<x-wirekit::checkbox name="terms" label="I agree to the terms of service" />

States

{{-- Unchecked --}}
<x-wirekit::checkbox name="c1" label="Ship on Friday" />

{{-- Checked --}}
<x-wirekit::checkbox name="c2" label="Ship on Friday" checked />

{{-- Indeterminate --}}
<x-wirekit::checkbox name="c3" label="Ship on Friday" indeterminate />

{{-- Disabled --}}
<x-wirekit::checkbox name="c4" label="Ship on Friday" disabled />

{{-- Disabled and checked --}}
<x-wirekit::checkbox name="c5" label="Ship on Friday" disabled checked />

Every state here is one a prop sets. Hover, focus and active are deliberately absent: no stylesheet can put an element into a pseudo-class, so a picture of one would show a state drawn by the page rather than by the component.

Sizes

Three sizes scale the box and its checkmark together — sm, md (default), and lg. They line up with the matching size on Radio and Toggle so a form mixing the controls stays visually consistent.

<x-wirekit::stack gap="sm">
    <x-wirekit::checkbox name="cs1" size="sm" label="Small" checked />
    <x-wirekit::checkbox name="cs2" size="md" label="Medium (default)" checked />
    <x-wirekit::checkbox name="cs3" size="lg" label="Large" checked />
</x-wirekit::stack>

Card Variant

variant="card" turns the whole control into a bordered, fully-clickable card that highlights when checked — the canonical "selectable option" pattern for feature toggles and multi-select grids. The card reacts to its own input via CSS :has(), so it needs no JavaScript.

<x-wirekit::stack gap="sm">
    <x-wirekit::checkbox name="feat-cache" variant="card" label="Response caching — speed up repeat requests" checked />
    <x-wirekit::checkbox name="feat-minify" variant="card" label="Minify HTML — smaller payloads" />
</x-wirekit::stack>

With Hint

<x-wirekit::checkbox name="newsletter" label="Subscribe to newsletter" hint="Monthly product updates, unsubscribe anytime." />

With Error

<x-wirekit::checkbox name="required" label="I must check this" error="This field is required." />

Errors from Laravel's validation bag are shown automatically when name matches a field, also for a nested name such as items[0][qty], whose error Laravel stores as items.0.qty, and for a list such as tags[]. In a Livewire form, the error disappears once the field passes validation.

Indeterminate State

The indeterminate state is useful for "parent" checkboxes when only some of their children are checked — e.g. a "Select all" control. The demo below uses Alpine.js to keep the parent in sync with its children:

<div x-data="{
        items: { php: false, js: true, css: false },
        get checkedCount() { return Object.values(this.items).filter(Boolean).length; },
        get total() { return Object.keys(this.items).length; },
        get allChecked() { return this.checkedCount === this.total; },
        get someChecked() { return this.checkedCount > 0 && this.checkedCount < this.total; },
        toggleAll(state) { Object.keys(this.items).forEach(k => this.items[k] = state); }
    }">
    <x-wirekit::checkbox
        id="select-all-demo"
        label="Select all items"
        x-bind:checked="allChecked"
        x-bind:indeterminate="someChecked"
        x-on:change="toggleAll($event.target.checked)"
    />
    <x-wirekit::stack gap="xs" class="mt-2 pl-6">
        <x-wirekit::checkbox id="stack-php" label="PHP" x-model="items.php" />
        <x-wirekit::checkbox id="stack-js" label="JavaScript" x-model="items.js" />
        <x-wirekit::checkbox id="stack-css" label="CSS" x-model="items.css" />
    </x-wirekit::stack>
</div>

The indeterminate state is set via the DOM property input.indeterminate = true — there is no HTML attribute for it, so the server cannot render it and something has to apply it after every render.

WireKit emits data-wk-indeterminate="true|false" on the input in both states and watches it. That is deliberately not x-init, which runs once: the third state almost always arrives after the first render — a Livewire round trip morphs the element, the attribute text changes, Alpine does not re-initialize, and the property keeps its old value. The box then reads as "none selected" while something is selected, which is exactly the state it exists to show. The attribute is also written when the prop is false, so returning to a determinate state has something to undo it.

It is not x-effect either. An effect over a value the server rendered re-runs exactly as often as x-init does — once — so x-effect is right where the value is reactive Alpine state (as in data-table) and wrong here.

x-bind:indeterminate (above) is the other half and stays as it is: it reacts to live Alpine state, which is a different source from the server-rendered prop.

Important: When binding an array-style name (e.g. name="stack[]") with Alpine's x-model, drop the value="..." attribute and bind to a boolean state (one key per checkbox), not to an array. With value present, Alpine expects x-model to target an array and will silently mis-render the checked state. WireKit auto-generates unique DOM ids for array-style names so <label for> keeps working, but the x-model / value semantics remain your responsibility.

With Rich Label (Slot)

For labels that contain links or formatting — common in GDPR/privacy consent checkboxes — use the default slot instead of the label prop:

<x-wirekit::checkbox name="consent-basic">
    I accept the
    <x-wirekit::link href="/privacy">Privacy Policy</x-wirekit::link>
    and
    <x-wirekit::link href="/terms">Terms of Service</x-wirekit::link>.
</x-wirekit::checkbox>

The slot content is rendered as raw HTML, so links, <strong>, <em>, and other inline elements work. When both label and slot content are provided, the slot takes precedence.

Open Links in a Modal

A common pattern for newsletter sign-ups: link the privacy policy and terms to static pages that open in a WireKit modal instead of navigating away.

<div x-data>
    <x-wirekit::checkbox name="consent-modal">
        I accept the
        <x-wirekit::link as="button"
            x-on:click.prevent.stop="window.dispatchEvent(new CustomEvent('wirekit-modal-show', { detail: { name: 'privacy-demo' } }))">Privacy Policy</x-wirekit::link>
        and
        <x-wirekit::link as="button"
            x-on:click.prevent.stop="window.dispatchEvent(new CustomEvent('wirekit-modal-show', { detail: { name: 'terms-demo' } }))">Terms of Service</x-wirekit::link>.
    </x-wirekit::checkbox>

    <x-wirekit::modal name="privacy-demo" size="lg">
        <x-wirekit::modal.header>Privacy Policy</x-wirekit::modal.header>
        <x-wirekit::modal.body>
            <p>Your static privacy policy content would go here — e.g. via <code>&#64;include('legal.privacy')</code>.</p>
        </x-wirekit::modal.body>
    </x-wirekit::modal>

    <x-wirekit::modal name="terms-demo" size="lg">
        <x-wirekit::modal.header>Terms of Service</x-wirekit::modal.header>
        <x-wirekit::modal.body>
            <p>Your static terms of service content would go here.</p>
        </x-wirekit::modal.body>
    </x-wirekit::modal>
</div>

The <button type="button"> prevents the checkbox from toggling when clicking a link (the .stop modifier makes sure the click doesn't bubble up to the label and retrigger a toggle). The modal opens by dispatching wirekit-modal-show directly on window — this guarantees the listener is hit regardless of DOM position.

Why the <div x-data> wrapper? Alpine directives (x-on, $dispatch, $refs, …) only work inside an x-data scope. Without it, x-on:click on the inline buttons would be silently ignored. The x-data can be empty — its job here is simply to activate the Alpine component tree.

Livewire Integration

Bind a checkbox to a boolean Livewire property via wire:model.live for single-toggle controls. For multi-select groups, share a name="…[]" across the group with a unique value per checkbox and bind every input to the same array property — the framework collects checked values into the array.

<x-wirekit::checkbox name="terms" label="Accept terms" wire:model.live="acceptedTerms" />

{{-- Array binding (multi-select) --}}
<x-wirekit::checkbox name="tags[]" value="php" label="PHP" wire:model.live="selectedTags" />
<x-wirekit::checkbox name="tags[]" value="js" label="JavaScript" wire:model.live="selectedTags" />

A single checkbox needs a bool property, or a model attribute with a boolean cast. A number, such as a tinyint column without the cast, is taken for the box's value rather than its state, so the box shows unchecked whatever the property holds and does not follow a value the server sets. In debug mode the component logs a warning for a binding to a number.

Optimistic UI

Pass the name of the Livewire method this component should call and the change appears immediately, then confirms or undoes itself when the server answers:

<x-wirekit::checkbox
    name="notify"
    label="Notify me"
    :checked="$notify"
    optimistic="toggleNotify"
/>

Load wirekit-optimistic.js alongside whichever bundle you already use — it is a separate file so applications that do not use it pay nothing for it:

@wirekitScripts
<script src="{{ asset('vendor/wirekit/wirekit-optimistic.js') }}" defer></script>

Try it

The demo below runs the real path: the change shows immediately, the outline says it is provisional, and the server's answer either confirms it silently or takes it back.

{{-- In your app there is no host: your own Livewire component owns the method. --}}
<x-wirekit::checkbox
    name="notify"
    label="Notify me"
    :checked="$notify"
    optimistic="toggleNotify"
/>

The <livewire:demos.…> wrapper above exists only on this site — it supplies the demo methods so the page can show a real round trip. The block under it is what you write.

The browser has already ticked the box by the time any handler runs, so what this adds is the confirmation, the undo, and the announcement. Pass the current value with :checked so the component knows where it started; optimistic replaces wire:model.live rather than joining it.

What a screen reader hears is the same for every component that supports this, and it is written out in full — one hedged announcement at the change, silence on confirmation, one more only if the server refuses, and focus that never moves — in Optimistic UI — the announcement contract. That page is also where the boundary is stated: this covers mutations, not sorting, filtering or pagination.

Props

Slots

All other attributes pass through to <input>, including name, id, checked, disabled, value, wire:model.

Accessibility

• Uses a native <input type="checkbox"> — all keyboard and screen-reader behavior is inherited from the browser.
• The visual box and checkmark are purely decorative (aria-hidden="true").
• Focus ring appears on the box when the hidden input receives keyboard focus.
• aria-invalid and aria-describedby are set automatically when error or hint are present.
• Inside <x-wirekit::field.set>, the checkbox also points at the group's hint, or at the group's error while it carries aria-invalid. A message for the group renders once, above the checkboxes.
• A label in another language than the page, such as a language's own name, takes lang. It goes on the label, which holds the words and the checkbox, so a screen reader says them in that language's voice:

<x-wirekit::checkbox name="languages[]" value="ja" label="日本語" lang="ja" />

Keyboard Interaction

Pitfalls

• Don't omit <x-wirekit::label> association. Labeling via the component's label prop (or the <x-slot:label> slot) is what makes the entire label clickable AND announces the binding to screen readers.
• Don't wrap a checkbox in a <button>. The component already renders an interactive <input type="checkbox"> — wrapping it in another interactive element confuses focus order.

Design Tokens

Personalization blocks

Three visual zones are resolvable through WireKit::personalize() / WireKit::scope(), and a config override under components.checkbox.classes.{block} reaches the same keys:

Making the checkbox a full-width row

The default label is inline-flex, so it is exactly as wide as its content. That is right for a consent line and wrong for an option list, where a code or a count belongs at the row's right edge: with an inline-flex wrapper there is no edge to push it to, and flex-1 inside the slot has nothing to stretch against.

Passing class="flex w-full" on the tag does not change this — the attribute bag is spread onto the <input>, not onto the <label>. Swap the display mode through the label block instead, and register it as a scope so only the call sites that want a row get one:

// app/Providers/AppServiceProvider.php
use Pushery\WireKit\WireKit;

public function boot(): void
{
    WireKit::scope('option-row', [
        'checkbox' => [
            'classes' => [
                // A closure receives the shipped classes, so this stays a delta rather
                // than a copy you now own — the rest of the block keeps updating with you.
                'label' => fn (string $vendor): string => str_replace('inline-flex', 'flex w-full', $vendor),

                // `flex` here too, not only `flex-1`: the span stretches to the row's width
                // as a flex ITEM, but its own children stay inline until it is a flex
                // CONTAINER, and `ms-auto` on the trailing element has nothing to act on.
                'text' => 'flex min-w-0 flex-1 items-center gap-[var(--gap-wk-sm)] text-[length:var(--text-wk-md)] text-[color:var(--color-wk-text)] select-none',
            ],
        ],
    ]);
}

<x-wirekit::checkbox name="attributes[]" value="{{ $attribute->id }}" scope="option-row">
    <span class="truncate">{{ $attribute->name }}</span>
    <span class="ms-auto shrink-0 text-[length:var(--text-wk-xs)] text-[color:var(--color-wk-text-muted)]">{{ $attribute->code }}</span>
</x-wirekit::checkbox>

The text block is also what decouples the label's text size from the size prop, which sizes the box only.

Further Reading

• MDN: <input type="checkbox">
• WAI-ARIA Checkbox Pattern
• MDN: aria-checked — when building custom checkboxes
• MDN: :checked pseudo-class