Components / Checkbox

Checkbox

# Introduction

A checkbox is best used for simple, list-like selections or when multiple options can be chosen independently. Use checkboxes for non-critical or batch actions and toggles for instant feedback or state changes.

Toggle is more suitable for binary on/off actions, especially when the action takes immediate effect, like enabling a feature or setting.

# Usage

There are no required children of the <zinq:checkbox> component.

  
<zinq:checkbox />

# Customization

The Checkbox component can be customized in many ways.

# Label

The Checkbox component can have its own label.

  
<zinq:checkbox>Remember me</zinq:checkbox>

But also you can set the label by using the label attribute.

  
<zinq:checkbox label="Options">Remember me</zinq:checkbox>

# Sizing

The Checkbox component comes in three sizes: default , sm , and lg . By default, the size is default .

  
<div class="flex flex-col space-y-3">
    <zinq:checkbox size="sm">Remember me</zinq:checkbox>
    <zinq:checkbox>Remember me</zinq:checkbox>
    <zinq:checkbox size="lg">Remember me</zinq:checkbox>
</div>

# Disabled

The Checkbox component can be disabled by setting the disabled attribute.

  
<zinq:checkbox disabled>Remember me</zinq:form.checkbox>

# Controlled

The Checkbox component state can be changed from any other component. You can simply use Alpine's @click directive to toggle the state.

Just define an id for the checkbox and use the Alpine.store to change the state.

Toggle checkbox
  
<zinq:checkbox id="my-checkbox-id">Remember me</zinq:form.checkbox>
<div class="mt-4">
    <zinq:badge
        @click="Alpine.store('zinq_checkboxes')['my-checkbox-id'].checked = !Alpine.store('zinq_checkboxes')['my-checkbox-id'].checked"
        class="cursor-pointer select-none"
    >Toggle checkbox</zinq:badge>
</div>

# Default State

You can set the default state of the checkbox by setting the checked attribute.

  
<zinq:checkbox checked>Remember me</zinq:form.checkbox>

# Livewire

You can use the wire:model directive to bind the Checkbox to a Livewire property.

  
<zinq:checkbox wire:model="remember">Remember me</zinq:checkbox>

# Live

You can also use wire:model.live to update the model on every state change.

Remember: NO
  
public bool $remember = false;

public function render(): string
{
    $label = '<zinq:badge ' . ($this->remember ? ' success>YES' : ' danger>NO') . '</zinq:badge>';

    return <<<HTML
        <div>
            <div class="mb-4 flex items-center space-x-2"><span>Remember:</span> {$label}</div>
            <zinq:checkbox wire:model.live="remember">Remember me</zinq:checkbox>
        </div>
    HTML;
}

# Validation errors

The Checkbox component will automatically display validation errors for you when wire:model attribute is used.

  
#[Rule('accepted')]
public bool $remember = false;

public function save(): void
{
    $this->validate();
}

public function render(): string
{
    return <<<HTML
        <zinq:form action="save">
            <zinq:checkbox wire:model="remember">Remember me</zinq:checkbox>
            <zinq:button>Save to see validation error</zinq:button>
        </zinq:form>
    HTML;
}

# Manual validation errors

Or you can manually display validation errors by using the error attribute.

Custom error message goes here.
  
<zinq:checkbox error="Custom error message goes here.">Remember me</zinq:checkbox>