Switch Toggle

{note} You're browsing the documentation for an old version of laravel-form-components. Consider upgrading your project to v8. Check your version with the following command:

`composer show rawilk/laravel-form-components`

• Introduction
• Installation
• Basic Usage
• Labels
  • Left aligned labels
• Handling values
  • Custom on and off values
• Variations
  • Short Toggle
  • Sizing
• Icons

#Introduction

The switch-toggle component offers an easy alternative to a traditional checkbox and is heavily based on the Tailwind UI toggle component. The switch toggle acts like a checkbox, however it allows for an "off" value and an "on" value; see custom on and off values for more info.

#Installation

While the switch-toggle component works out-of-the-box when you've set the directive, we recommend that you install and compile the JavaScript libraries before you deploy to production:

• Alpine.js ^2.8

#Basic Usage

The most basic usage of the component is just by calling it:

<x-switch-toggle />

This will render a toggle element similar to the example shown for the "Simple toggle" on Tailwind UI.

#Labels

You can easily add a label to the switch toggle by using the label attribute:

<x-switch-toggle label="Notifications on" />

This will render a label containing the text "Notifications on" to the right side of the switch.

#Left aligned labels

You can also render labels on the left of switch by setting label-position to left:

<x-switch-toggle label="Notifications on" label-position="left" />

Now "Notifications on" will be rendered to the left of the switch.

#Handling values

The switch toggle component offers support for both wire:model and wire:model.defer right out of the box, and is the recommended way to use this component when you are using Laravel Livewire. Behind-the-scenes, the component will use the @entangle blade directive from livewire to bind the value to a local variable on the component.

<x-switch-toggle wire:model.defer="allowNotifications" label="Notifications on" />

For non-livewire forms, you may also give the component a value to use for the initial value, but be sure to include a name attribute so that your server can receive the value from the switch in a normal form submission.

<x-switch-toggle name="foo" :value="true" />

When the component is given a name attribute, it will render a hidden input so that the current value of the component is passed on to the server via a form submission. The hidden input rendered from the example above will look like this:

<input type="hidden" name="foo" x-bind:value="JSON.stringify(value)" />

#Custom on and off values

The switch toggle is not limited to true and false values for its respective "on" and "off" values; it can use strings and integer values as well:

<x-switch-toggle on-value="foo" off-value="bar" />

Now when the switch is "off", the value will be "bar", and when it is "on", the value will be "foo".

#Variations

Different size and style variations of the switch may be rendered out-of-the-box:

#Short Toggle

Based on the short toggle example from Tailwind UI, the short toggle will make the size of the circle on the bar larger than the height of the bar. All you need to do for this style is set the short flag to true:

<x-switch-toggle short />

#Sizing

Both the simple and short toggle variations allow for different sizing out-of-the-box. Simply pass in a size to the component to re-size it:

<x-switch-toggle size="lg" />

Here are the sizes the package provides by default for each variation:

Simple:

• sm
• base (default)
• lg

Short:

• base (default)
• lg

These sizes also come in responsive variants, so if you wanted the switch small on small screens, but large on larger screens, you could do something like this:

<x-switch-toggle class="switch-toggle--sm lg:switch-toggle--lg" />

You are free to add your own sizes in your own stylesheets. Just reference the switch toggle styles for guidance.

#Icons

Based on the toggle with icon from Tailwind UI, the switch toggle component allows you to specify icons to display on the button for both "on" and "off" states:

<x-switch-toggle>
    <x-slot name="offIcon">
        <x-heroicon-s-x class="w-3 h-3 text-gray-400" />
    </x-slot>
    
    <x-slot name="onIcon">
        <x-heroicon-s-check class="w-3 h-3 text-blue-600" />
    </x-slot>
</x-switch-toggle>

In this example, you will see an "x" icon when the switch is "off", and a checkmark icon when the switch is "on".

{note} This example requires the blade heroicon package.