#Checkbox Component

#Introduction

The checkbox component provides a powerful and flexible foundation for checkbox input fields.

#Installation

Use the sheaf artisan command to install the checkbox component easily:

php artisan sheaf:install checkbox

#Basic Usage

<x-ui.checkbox 
    wire:model="agreed"
    label="I agree to the terms and conditions"
    description="By checking this box, you agree to abide by our terms and conditions."
/>

#Integration

#Bind To Livewire

To use with Livewire you need to only use wire:model="agreed" to bind your checkbox state:

<x-ui.checkbox 
    wire:model="agreed"
    label="I agree to the terms and conditions"
    description="By checking this box, you agree to abide by our terms and conditions."
/>

#Using it within Blade & Alpine

You can use it outside Livewire with just Alpine (with Blade):

<div x-data="{ agreed: false }">
    <x-ui.checkbox 
        x-model="agreed"
        label="I agree to the terms and conditions"
        description="By checking this box, you agree to abide by our terms and conditions."
    />
</div>

#Managing State

#Individual Checkbox (Boolean State)

For single checkboxes that manage their own boolean state, bind directly to the checkbox:

    <x-ui.checkbox 
        wire:model="agreed"
        label="I agree to the terms and conditions"
        description="By checking this box, you agree to abide by our terms and conditions."
    />

#Checkbox Group (Array State)

For multiple checkboxes that should manage a shared array of values, bind the model to the group wrapper only:

<!-- Group manages array state - bind model to GROUP only -->
<x-ui.checkbox.group wire:model="skills">
    <x-ui.checkbox 
        label="Laravel"
        value="laravel"
        description="A powerful PHP web framework with elegant syntax for building modern web applications quickly."
    />
    <x-ui.checkbox 
        label="PHP" 
        value="php"
        description="Popular server-side scripting language for creating dynamic websites and web applications." 
    />
    <x-ui.checkbox 
        label="Alpine.js"
        value="alpinejs"
        description="Lightweight JavaScript framework for adding reactive behavior to HTML without complexity."
    />
    <x-ui.checkbox
        label="Livewire"
        value="livewire"
        description="Laravel framework for building dynamic UIs using PHP instead of JavaScript."
    />
    <x-ui.checkbox 
        label="Tailwind CSS"
        value="tailwind"
        description="Utility-first CSS framework for rapid custom design development."
    />
</x-ui.checkbox.group>

Important: When using groups, only add the wire:model or x-model to the <x-ui.checkbox.group> component, not to individual checkboxes. The group automatically manages the array state.

#Understanding State Management

The checkbox system intelligently adapts based on context:

#Individual Mode

• Each checkbox manages its own boolean state
• Use wire:model directly on the checkbox
• Perfect for independent settings and toggles

#Group Mode

• Group manages a shared array of selected values
• Use wire:model only on the group wrapper
• Individual checkboxes provide their value to the array
• Perfect for multi-select scenarios

<!-- INDIVIDUAL MODE: Separate boolean states -->
<x-ui.checkbox wire:model="terms" label="Accept terms" />
<x-ui.checkbox wire:model="privacy" label="Accept privacy policy" />
<x-ui.checkbox wire:model="newsletter" label="Subscribe to newsletter" />

<!-- GROUP MODE: Single array state -->
<x-ui.checkbox.group wire:model="preferences">
    <x-ui.checkbox value="email" label="Email notifications" />
    <x-ui.checkbox value="sms" label="SMS notifications" />
    <x-ui.checkbox value="push" label="Push notifications" />
</x-ui.checkbox.group>

#Checkbox States

#Basic States

<x-ui.checkbox wire:model="basic" label="Basic checkbox" />
<x-ui.checkbox wire:model="checked" label="Already checked" checked />
<x-ui.checkbox wire:model="partial" label="Partially selected" indeterminate />

#Disabled State

<x-ui.checkbox 
    wire:model="disabled"
    label="Cannot change this"
    disabled
/>

#Invalid State

<x-ui.checkbox 
    wire:model="disabled"
    label="Cannot change this"
    invalid
/>

#Sizes

The checkbox component supports multiple sizes to match your design needs:

<x-ui.checkbox size="xs" label="Extra small" />
<x-ui.checkbox size="sm" label="Small" />
<x-ui.checkbox size="md" label="Medium (default)" />
<x-ui.checkbox size="lg" label="Large" />

#Group Variants

Different layout styles for checkbox groups:

#Default Variant

Smart vertical spacing with content-aware gaps:

<x-ui.checkbox.group wire:model="notifications">
    <x-ui.checkbox 
        value="email" 
        label="Email notifications"
        description="Receive important updates via email"
    />
    <x-ui.checkbox value="sms" label="SMS notifications" />
    <x-ui.checkbox value="push" label="Push notifications" />
</x-ui.checkbox.group>

#Pills Variant

Horizontal layout with wrapping, perfect for tags and skills:

<x-ui.checkbox.group wire:model="skills" variant="pills">
    <x-ui.checkbox label="Laravel" value="laravel" />
    <x-ui.checkbox label="Vue.js" value="vuejs" />
    <x-ui.checkbox label="React" value="react" />
    <x-ui.checkbox label="Tailwind CSS" value="tailwind" />
</x-ui.checkbox.group>

#Cards Variant

Full card-like components with enhanced spacing and hover effects:

<x-ui.checkbox.group wire:model="features" variant="cards">
    <x-ui.checkbox 
        value="analytics"
        label="Advanced Analytics Dashboard"
        description="Get detailed insights with custom reports and real-time metrics."
    />
    <x-ui.checkbox 
        value="api"
        label="API Access & Webhooks"
        description="Full REST API access with webhook support."
    />
</x-ui.checkbox.group>

#Form Integration

#With Field Component

Use the field component for proper form structure:

<x-ui.field>
    <x-ui.label>Newsletter Subscription</x-ui.label>
    <x-ui.description>Receive updates about new features and announcements</x-ui.description>
    <x-ui.checkbox 
        wire:model="newsletter"
        label="Yes, I want to receive the newsletter"
    />
    <x-ui.error name="newsletter" />
</x-ui.field>

#Validation States

The checkbox automatically detects validation errors when used with Livewire:

<x-ui.field>
    <x-ui.label>Terms and Conditions</x-ui.label>
    <x-ui.checkbox 
        wire:model="terms"
        label="I agree to the terms and conditions"
    />
    <x-ui.error name="terms" />
</x-ui.field>

#Component Props

#Checkbox Props

#Checkbox Group Props