Z

Toggle / Switch

Binary on/off switch component powered by Alpine.js. Perfect for settings and feature toggles with smooth animations and clear visual states.

Component Props

Prop Type Default Description
name string null Input name for form submission (optional)
checked bool false Initial ON/OFF state
disabled bool false Disabled state
ariaLabel string null Required accessible label
size string 'md' Size: sm, md, lg
class string '' Additional wrapper classes

Sizes

Small

Medium (Default)

Large

States

OFF (Unchecked)

Click to enable

ON (Checked)

Click to disable

Disabled (OFF)

Disabled in OFF state

Disabled (ON)

Disabled in ON state

Real-World Examples

Notification Settings

Privacy Settings

Feature Toggles

Size Variations

Usage Example

Basic Usage

<x-building-blocks.toggle 
    name="notifications" 
    ariaLabel="Enable notifications"
>
    Enable notifications
</x-building-blocks.toggle>

Pre-enabled (ON)

<x-building-blocks.toggle 
    name="auto_save" 
    :checked="true"
    ariaLabel="Enable auto-save"
>
    Auto-save
</x-building-blocks.toggle>

Different Size

<x-building-blocks.toggle 
    name="feature" 
    size="lg"
    ariaLabel="Enable feature"
>
    Large toggle
</x-building-blocks.toggle>

Disabled

<x-building-blocks.toggle 
    name="locked_feature" 
    :checked="true"
    :disabled="true"
    ariaLabel="Locked feature"
>
    Required feature (locked)
</x-building-blocks.toggle>

Key Features

  • Alpine.js Powered: Smooth, reactive state management
  • Smooth Animation: Fluid thumb movement and color transitions
  • Clear States: Distinct ON (primary) and OFF (neutral) visual states
  • Three Sizes: Small, medium, and large variants
  • Touch-Friendly: Large enough for easy mobile interaction
  • WCAG 2.1 AA: Fully accessible with keyboard support

Best Practices

Do:

  • Use toggles for binary on/off settings
  • Always provide an ariaLabel for accessibility
  • Use clear labels that describe what the toggle controls
  • Show immediate effect when toggled (no save button needed)
  • Use consistent toggle placement in settings lists

Don't:

  • Don't use toggles for mutually exclusive options (use radio buttons)
  • Don't use toggles for actions that require confirmation
  • Don't use toggles without clear labels
  • Don't make users save after toggling (apply immediately)

Accessibility Features

  • Keyboard Navigation: Space to toggle, Tab to navigate
  • Focus Ring: Clear visual indicator for keyboard users
  • ARIA Labels: Required ariaLabel ensures screen reader compatibility
  • State Announcement: Screen readers announce ON/OFF state changes