Inputs

Switch Toggle

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's mostly used for an on/off state.

The switch-toggle component requires the following third-party libraries to work properly:

  • Alpine.js

See Third-Party Assets on the installation guide for further setup information.

If you're going to use different colors on the switch, be sure to include the switch-toggle plugin in your tailwind config. See Plugins for more information.

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.

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. You can also use the default slot to render the label as well:

<x-switch-toggle> Notifications on </x-switch-toggle>

You can also render labels on the left of switch by using the labelLeft attribute.

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

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

The component allows for labels to be placed on both the left and right side of the switch at the same time.

<x-switch-toggle label-left="Off" label="On" />

This will render "Off" to the left, and "On" to the right.

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"
/>

{tip} x-model can be used instead if you're not using Livewire in the form.

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" />

{note} Only true/false values are supported for the on/off values when used this way.

The switch toggle is not limited to true and false values for its respective on and off states; 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".

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

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 attribute to true:

<x-switch-toggle short />

If you're not using the short variation, you can adjust the size of the switch via the size attribute. The currently supported sizes are: sm, md, lg, with md being the default.

<x-switch-toggle size="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" />

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 on-icon="heroicon-m-check" off-icon="heroicon-m-x-mark" />

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.

You may also render the icons via slot instead if you prefer:

<x-switch-toggle>
    <x-slot:on-icon>
        <x-heroicon-m-check />
    </x-slot:on-icon>

    <x-slot:off-icon>
        <x-heroicon-m-x-mark />
    </x-slot:off-icon>
</x-switch-toggle>

{note} Icons are not supported when the short attribute is set to true.

By default, the switch-toggle component is configured to show a blue background when it is in an "on" state. Given you have the switch-toggle Tailwind plugin included in your tailwind config file, you will be able to use any of your application's configured colors for the switch using the color attribute.

<x-switch-toggle color="red" />
prop description
name The name of the input
id The id of the input. Defaults to name
value The initial value of the input. Disregarded if wire:model or x-model present.
onValue The value for when the switch is "on". Defaults to true
offValue The value for when the switch is "off". Defaults to false
label Text to display to the right of the switch.
labelLeft Text to display to the left of the switch.
containerClass A CSS class to apply to the container of the switch.
disabled Disable the switch
size The size of the switch. Defaults to md
color The color of the switch when it is "on". Defaults to blue
onIcon An icon to display on the switch when it is in an "on" state
offIcon An icon to display on the switch when it is in an "off" state
short Display switch as the "short" style. Sizing does not apply to this style.
extraAttributes Pass an array of attributes to apply to the input
slot description
label Text to display to the right of the switch.
labelLeft Text to display to the left of the switch.
onIcon An icon to display on the switch when it is in an "on" state
offIcon An icon to display on the switch when it is in an "off" state

The following configuration keys and values can be adjusted for common default behavior you may want for the switch-toggle element.

'defaults' => [
    'global' => [
        // Show error states by default.
        'show_errors' => true,
    ],

    'switch_toggle' => [
        // Apply a CSS class to the label that contains the switch toggle globally.
        'container_class' => null,

        // Apply a CSS class to the switch toggle (not the actual input element) globally.
        'input_class' => null,

        // Set the default size of the switch toggle.
        // Supported: 'sm', 'md', 'lg', (default is 'md')
        'size' => null,

        // Set the default color of the switch toggle. (e.g. "blue", "red", "green", etc.)
        'color' => null,

        // Set the default icon to show when the switch is in an "on" state.
        'on_icon' => null,

        // Set the default icon to show when the switch is in an "off" state.
        'off_icon' => null,
    ],
],
Previous
Date Picker
Caught a mistake? Suggest an edit on GitHub