Toggle

Fully customizable switch that can replace traditional checkboxes and radio buttons.

About

The Toggle component is a switch for a boolean value. It renders a checkbox by default, or a radio when you set type="radio", and carries role="switch" either way.

Example

The Toggle component can be used in various ways depending on your needs. Below is a basic example:

Svelte 
<script>
  import { Toggle } from "theui-svelte";
</script>

<Toggle name="toggle">Enable Feature</Toggle>

Use it in forms and settings panels, anywhere an on and off switch reads better than a checkbox.

Toggle Type

The type prop defines whether the toggle functions as a checkbox or a radio button.

Checkboxes

Radio buttons

Svelte 
<!-- Checkbox (default) -->
<Toggle name="toggle1" type="checkbox">Checkbox 1</Toggle>
<Toggle name="toggle2" type="checkbox">Checkbox 2</Toggle>

<!-- Radio buttons -->
<Toggle name="toggle3" type="radio" value="1">Radio button 1</Toggle>
<Toggle name="toggle3" type="radio" value="2">Radio button 2</Toggle>

Name and Value

The name and value props are what the form submission uses, whether the Toggle is a checkbox or a radio button.

  • The name prop is required for radio buttons to group multiple toggles under the same name, allowing only one to be selected at a time.
  • The value prop sets the value of the input. It can be anything: text, number or boolean. When used as a radio button, the value represents the option.
  • The checked prop controls the state of a checkbox toggle. It is false by default and can be bound with bind:checked.
  • The group prop holds the selected value of radio toggles with the same name. Bind it with bind:group to get the selected option.

Gender

Svelte 
<script>
  let notification = $state(false);
  let gender = $state();
</script>

<Toggle name="preferences" value="ok" bind:checked={notification}>Enable Notifications</Toggle>

<Toggle name="gender" type="radio" value="male" bind:group={gender}>Male</Toggle>
<Toggle name="gender" type="radio" value="female" bind:group={gender}>Female</Toggle>

Toggle Sizes

The size prop controls the dimensions of the toggle switch, allowing it to fit various UI designs. Whether you need a compact switch for minimal layouts or a larger one for better accessibility, the size prop provides flexibility. Available sizes are: sm, md (default), lg and xl.

Svelte 
<Toggle name="toggle" size="sm">Small (sm) toggle</Toggle>
<Toggle name="toggle" size="md">Medium (md) toggle</Toggle>
<Toggle name="toggle" size="lg">Large (lg) toggle</Toggle>
<Toggle name="toggle" size="xl">Extra large (xl) toggle</Toggle>

Animation

The animationSpeed prop sets how long the knob takes to slide across. Available values are: slower, slow, normal (default), fast, faster and none.

Svelte 
<Toggle name="toggle" animationSpeed="slower">Slower animation</Toggle>
<Toggle name="toggle" animationSpeed="slow">Slow animation</Toggle>
<Toggle name="toggle" animationSpeed="normal">Normal animation</Toggle>
<Toggle name="toggle" animationSpeed="fast">Fast animation</Toggle>
<Toggle name="toggle" animationSpeed="faster">Faster animation</Toggle>
<Toggle name="toggle" animationSpeed="none">No animation</Toggle>

Rounded Toggle

The rounded prop defines the shape of the toggle's switch and background. By adjusting this property, you can make the toggle appear more circular or squared. Available values are: sm, md, lg, xl, 2xl, full (default) and none.

Svelte 
<Toggle name="toggle" size="xl" rounded="sm">Small rounded</Toggle>
<Toggle name="toggle" size="xl" rounded="md">Medium rounded</Toggle>
<Toggle name="toggle" size="xl" rounded="lg">Large rounded</Toggle>
<Toggle name="toggle" size="xl" rounded="xl">Extra large rounded</Toggle>
<Toggle name="toggle" size="xl" rounded="full">Full rounded</Toggle>
<Toggle name="toggle" size="xl" rounded="none">Not rounded</Toggle>

Label Position

The labelPosition prop controls where the label sits. It accepts "end" (default), which places the label after the toggle, and "start", which places it before. The position follows the writing direction, so in a right-to-left layout "start" puts the label on the right.

Svelte 
<Toggle name="toggle">Label after the toggle</Toggle>
<Toggle name="toggle" labelPosition="start">Label before the toggle</Toggle>

Resetting Style

The reset prop removes all default styles from the Toggle component, so only the classes you pass are applied. This is useful when you want full control over the design. It is inherited from the nearest Fieldset or Form, so a whole form can be reset at once.

Svelte 
<Toggle name="toggle" reset class="w-10 h-5 appearance-none rounded-full bg-green-200 checked:bg-green-500">Reset toggle</Toggle>

Disabled Toggle

Add the native disabled or readonly attribute to prevent changes. The toggle and its label are dimmed and can not be clicked.

Svelte 
<Toggle name="toggle" disabled>Disabled toggle</Toggle>
<Toggle name="toggle" checked disabled>Disabled toggle (on)</Toggle>

Customization

The Toggle component offers flexibility in styling through the labelClasses, wrapperClasses, and class props, allowing you to adjust the appearance of both the label and the toggle's outer container.

class
The class attribute can be used to apply custom styles directly to the toggle input. This gives you full control over its appearance, making it easy to align with your design system.

wrapperClasses
The wrapperClasses prop lets you apply custom styles to the main wrapper <div>. By default, it is an empty string, meaning no additional styles are applied unless specified.

labelClasses
The labelClasses prop is inherited from the parent Fieldset or Form when there is one. The size, animationSpeed and reset props are inherited the same way. However, you can override it to apply custom styles to the label as needed.

Svelte 
<Toggle
  labelClasses="text-red-500 font-bold"
  wrapperClasses="shadow-xl py-2 px-4 bg-gray-100 dark:bg-gray-800 rounded-full"
  class="bg-blue-200 checked:hover:bg-green-500 checked:focus:bg-green-500 checked:bg-green-500 focus:!ring-gray-500 checked:focus:!ring-green-500"
>
  CUSTOM TOGGLE
</Toggle>

Accessibility

The Toggle carries role="switch" and keeps aria-checked in step with its state, so a screen reader reads out whether it is on or off. As a checkbox, aria-checked follows checked. As a radio, it is true when group matches the toggle's value. The label is tied to the input with for, so clicking the text flips the switch as well.

Configuration