Skip to content
Bladewell

<x-widget.checkbox>

Checkbox Blade component for Laravel and Livewire

A checkbox with a label or a label slot, a description, and an optional value for when it is off. Works with Livewire wire:model, as one box or a list on an array.

php artisan bladewell:add checkbox
Also adds
Icon
Works with
Laravel 12 and 13, Livewire 3 and 4, Tailwind CSS 4.1+, PHP 8.3+
Guides
Build a Laravel form from your validation rules · Passkey sign-in for Laravel with Fortify

Usage

Livewire

In a Livewire component, bind with wire:model (deferred) or wire:model.live; no name is needed. One box binds a bool: public bool $terms = false. Several boxes on the same array property each add their value to it: public array $channels = ['email']. The boxes show the property after every render, so ticking or clearing it in PHP updates them. Errors are read under the property, channels.* included.

Blade
<div class="space-y-5">
    <x-widget.checkbox label="I agree to the terms" wire:model="terms" />

    <div class="space-y-2">
        <x-widget.checkbox label="Email" value="email" wire:model.live="channels" />
        <x-widget.checkbox label="SMS" value="sms" wire:model.live="channels" />
        <x-widget.checkbox label="Push" value="push" wire:model.live="channels" />
    </div>
</div>

On the server

The checkbox can't stop a request that skips it. Here's what to check on your server.

Security

  • An unticked box sends nothing, so a value left out of the request never turns off. Read it with $request->boolean(), or give the box unchecked-value="0", and validate it with boolean.

    Laravel: Boolean input · Laravel: The boolean rule

  • For terms or consent, validate with accepted, and consider saving when it was given and to which version, so you can show it later.

    Laravel: The accepted rule

Examples

Checkbox

The label can be a slot, for links. After a failed submit, the box keeps the state the user left it in. unchecked-value="0" sends a value when it's off, for boolean columns.

Show code
Blade
<div class="flex flex-col gap-4">
    <x-widget.checkbox name="terms" required>
        I agree to the <a href="#terms" class="text-link underline">terms of service</a>
    </x-widget.checkbox>
    <x-widget.checkbox name="newsletter" label="Email me product news" description="About once a month. Unsubscribe any time." unchecked-value="0" checked />
</div>

Props

Other attributes, such as autocomplete or data-*, are passed through to the element. class styles the component's outer wrapper.

<x-widget.checkbox>

Prop Default Description
name null What it submits as; its error and old input are found under it. Optional with wire:model, which then names it.
id null Defaults to one made from the name (or the wire:model property).
label null Beside the box, and its name for screen readers. Or use the slot for markup (a link to the terms).
description null Smaller text under the label.
value '1' What it submits when ticked.
checked false Ticked to start with. Old input wins after a failed submit; with wire:model, the bound property.
unchecked-value null Also submits this when unticked (e.g. 0), so the field is always in the request.
error null An error message of your own; otherwise the validation error for the name, from the session or Livewire.
info null A hint under the field.
bag 'default' Which error bag to read the error from.
disabled false Greyed out: it can't be changed.
readonly false Shown, and submitted, but it can't be changed. With disabled, disabled wins.

Accessibility

The example above is checked with axe-core against the WCAG 2.2 A and AA rules, in the light theme and the dark one, both as the page draws and with each popover, dialog, toast and tooltip opened, on every change. A change that fails can't be merged. Where axe can't decide, such as contrast on SVG text, the test measures the colours itself instead of letting it pass.

Automated checks can't judge everything: how it sounds in a screen reader, and how it feels to use from the keyboard, still need a person. Check those on your own pages too.

Source

What bladewell:add checkbox writes to your app with the default namespaces. Prefer to copy by hand? Take these files, plus the ones from the components it also adds and Field, and the theme and base CSS.

resources/views/components/widget/checkbox/index.blade.php Show
index.blade.php
app/View/Widget/ElementIds.php Show
ElementIds.php
app/View/Widget/FormField.php Show
FormField.php