# 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: ```html Enable Feature ``` 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. ```html Checkbox 1 Checkbox 2 Radio button 1 Radio button 2 ``` ## 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. ```html Enable Notifications Male Female ``` ## 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`. ```html Small (sm) toggle Medium (md) toggle Large (lg) toggle Extra large (xl) 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`. ```html Slower animation Slow animation Normal animation Fast animation Faster animation No animation ``` ## 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`. ```html Small rounded Medium rounded Large rounded Extra large rounded Full rounded Not rounded ``` > **Note:** Note: the "xl" size is used here so the switch is easy to see in the demo. ## 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. ```html Label after the toggle Label before the 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. ```html Reset 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. ```html Disabled toggle Disabled toggle (on) ``` ## 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 . 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. ```html CUSTOM 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 ### Props | Name | Type | Default | Description | | --- | --- | --- | --- | | `type` | "checkbox" \| "radio" | `checkbox` | Specifies whether the toggle functions as a checkbox or a radio button. | | `value` | unknown | `undefined` | Value of the toggle input. It could be anything, text, numeric or boolean! | | `checked` | boolean | `false` | The checked state of a checkbox toggle. Bindable with `bind:checked`. | | `group` | unknown | `undefined` | The selected value of a radio toggle group. Bindable with `bind:group`. | | `size` | [INPUT_SIZE](https://www.theui.dev/docs/types#input-size-type) | `Inherited from Fieldset or Form component or "md` | Defines the size of the toggle. | | `animationSpeed` | [ANIMATE_SPEED](https://www.theui.dev/docs/types#animation-speed-type) | `Inherited from Fieldset or Form component or "normal` | Controls the animation speed when toggling. | | `rounded` | [ROUNDED](https://www.theui.dev/docs/types#rounded-type) | `full` | Defines the border-radius of the toggle switch. | | `reset` | boolean | `Inherited from Fieldset or Form, or false` | If set to true, removes all default styles, allowing full customization. | | `wrapperClasses` | string | `` | Custom CSS classes applied to the wrapper div. | | `labelPosition` | 'start' \| 'end' | `end` | Places the label before ("start") or after ("end") the toggle, following the writing direction. | | `labelClasses` | string | `Inherited from Fieldset or Form component or "` | Custom CSS classes for styling the label. Inherits from the Fieldset or Form component if available. | ### Dynamic props | Name | Description | | --- | --- | | `disabled` | Disables the toggle and dims it together with its label. | | `readonly` | Prevents changes and dims the toggle together with its label. | ### Snippets | Name | Description | | --- | --- | | `children` | The label content of the toggle. | --- Category: Components Keywords: toggle, switch, form-input, component, svelte, svelte-5, theui-svelte, component-library, ui, tailwindcss Full documentation set: https://www.theui.dev/llms-full.txt