Toggle

A switch control for binary on/off settings. Toggles are visually distinct from checkboxes and communicate an immediate state change (like flipping a lightswitch) rather than a form selection to be submitted later.

Basic Usage

<x-wirekit::toggle name="notifications" label="Enable notifications" />

Sizes

<x-wirekit::toggle name="t1" label="Small" size="sm" />
<x-wirekit::toggle name="t2" label="Medium (default)" size="md" />
<x-wirekit::toggle name="t3" label="Large" size="lg" />

With Hint

<x-wirekit::toggle name="marketing" label="Marketing emails" hint="Occasional product updates, no more than once a month." />

States

<x-wirekit::toggle name="s1" label="On by default" checked />
<x-wirekit::toggle name="s2" label="Off and disabled" disabled />
<x-wirekit::toggle name="s3" label="On and disabled" checked disabled />

The State in Words and Colors

on-label and off-label write the state beside the switch. The word follows the click at once, before anything is saved, because it is drawn from the checkbox itself. A screen reader does not read it: the switch announces its own state. The words sit after the switch and its label, or before the switch with state-position="start", and they keep the width of the longer one, so nothing beside them moves when the switch flips.

on-intent and off-intent color the track for each state: accent, success, danger or neutral. On is accent and off is neutral unless you say otherwise. neutral is the plain off state, so an on-intent="neutral" switch tells its states apart by the knob alone.

<x-wirekit::toggle name="push" label="Push notifications" on-label="On" off-label="Off" on-intent="success" off-intent="danger" checked />
<x-wirekit::toggle name="digest" label="Weekly digest" hide-label on-label="Activated" off-label="Deactivated" state-position="start" on-intent="success" off-intent="danger" />

Livewire Integration

The toggle is a native <input type="checkbox"> — wire:model works out of the box:

<x-wirekit::toggle
    name="notify"
    label="Notify me"
    wire:model.live="notifyEnabled"
/>

Bind 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 toggle shows off 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 the toggle should call and it shows the new state immediately, then confirms or undoes it when the server answers:

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

Try it

The demo below runs the real path: the flip shows immediately, the outline says the value 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::toggle
    name="notify"
    label="Notify me"
    :checked="$notifyEnabled"
    optimistic="toggleNotify"
/>

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

It is a method name rather than a boolean because the component cannot know the action otherwise — server actions reach a WireKit component through the attribute bag, so the component never sees your wire:click.

optimistic replaces wire:model.live here rather than joining it. The method you name is what changes the value on the server, and the toggle shows the change while that call is in flight. Pass the current value with :checked so the toggle knows where it started; a plain wire:model (without .live) alongside it is still fine, since it only submits with the surrounding form.

Load wirekit-optimistic.js alongside whichever bundle you already use — below it, in your layout:

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

It is a separate file on purpose: loading it is how you opt into the announcement behavior described below, so applications that do not use it pay nothing for it. Without it the toggle keeps working exactly as it always has — the prop simply has nothing to mount.

A second flip while one is in flight is refused rather than queued. Queued, the final state would depend on the order the responses came back in — network timing — which is both wrong and impossible to test.

Scope. This covers mutations: changing something and showing it right away. Sorting, filtering, pagination and form submission are query round trips — nobody can show a result nobody knows yet — and are deliberately not covered.

Design Decisions

• Why role="switch" instead of role="checkbox"? A switch represents an immediate state change (the setting applies right away). A checkbox represents a selection in a form (applied on submit). This distinction matters for screen reader users.
• Why a native <input> instead of Alpine? Native inputs are zero-JS, fully compatible with Livewire's wire:model, and inherit form submission behavior for free.

<x-wirekit::toggle name="notifications" label="Enable notifications" error="Turn this on to receive the digest you subscribed to." />

Props

All other attributes (name, id, checked, disabled, wire:model, etc.) pass through to the underlying <input>.

Slots

Accessibility

• The underlying <input> has role="switch", which tells assistive technology this is an on/off control (not a standard checkbox).
• The visual track and knob are purely decorative (aria-hidden="true"). Screen readers announce the native input's checked state.
• The words from on-label and off-label are aria-hidden for the same reason: the switch already says whether it is on, and reading the word as well would say it twice.
• The accent, success and danger tracks keep at least 3:1 against the page and against the knob, in the default palette, light and dark.
• Focus ring appears on the track via peer-focus-visible:* utilities — keyboard users always see which toggle is focused.
• aria-invalid, aria-describedby are set automatically when error or hint are present.
• Inside <x-wirekit::field.set>, the toggle also points at the group's hint, or at the group's error while it carries aria-invalid.

Keyboard Interaction

The control is a native <input type="checkbox"> carrying role="switch", so it inherits the browser's own keyboard behavior: Space toggles it. Enter does not — inside a form a browser treats Enter on a checkbox as a submit, and the toggle binds no key handler that would change that. Enter is a button's key, and this control is not a button.

Pitfalls

• Don't use a toggle for an action that requires a confirmation step. Toggles should commit instantly; pair them with reversible state. For destructive actions use a button + <x-wirekit::alert-dialog>.
• Don't bind wire:model.live if the action is expensive. Each flick of the toggle round-trips. Debounce, or commit on a save button.

Design Tokens

Customization

Override defaults in config/wirekit.php:

'components' => [
    'toggle' => ['size' => 'lg'],
],