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

<x-wirekit::stack gap="sm">
    <x-wirekit::checkbox name="c1" label="Unchecked" />
    <x-wirekit::checkbox name="c2" label="Checked" checked />
    <x-wirekit::checkbox name="c3" label="Indeterminate (partial selection)" indeterminate />
    <x-wirekit::checkbox name="c4" label="Disabled" disabled />
    <x-wirekit::checkbox name="c5" label="Disabled + checked" disabled checked />
</x-wirekit::stack>

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. 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
    <a href="/privacy" style="text-decoration: underline; color: var(--color-wk-accent);">Privacy Policy</a>
    and
    <a href="/terms" style="text-decoration: underline; color: var(--color-wk-accent);">Terms of Service</a>.
</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
        <button type="button"
            style="text-decoration: underline; color: var(--color-wk-accent); background: transparent; border: none; padding: 0; cursor: pointer; font: inherit;"
            x-on:click.prevent.stop="window.dispatchEvent(new CustomEvent('wirekit-modal-show', { detail: { name: 'privacy-demo' } }))">Privacy Policy</button>
        and
        <button type="button"
            style="text-decoration: underline; color: var(--color-wk-accent); background: transparent; border: none; padding: 0; cursor: pointer; font: inherit;"
            x-on:click.prevent.stop="window.dispatchEvent(new CustomEvent('wirekit-modal-show', { detail: { name: 'terms-demo' } }))">Terms of Service</button>.
    </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" />

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') }}"></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.

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

Further Reading

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