Switch Toggle

• Introduction
• Installation
• Basic Usage
• Labels
  • Left aligned labels
  • Multiple Labels
• Handling values
  • Custom on and off values
• Variations
  • Short Toggle
  • Sizing
• Icons
• Colors
• API Reference
  • props
  • slots
  • config

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

#Installation

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.

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

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

#Left aligned labels

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.

#Multiple Labels

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.

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

{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.

#Custom on and off values

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

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

<x-switch-toggle short />

#Sizing

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

#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 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.

#Colors

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

#API Reference

#props

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

#slots

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

#config

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,
    ],
],