Switch

A toggle component for turning a single option on or off.

Enable notifications

<ui:switch.root>
    <ui:switch.label>Enable notifications</ui:switch.label>
    <div class="flex items-center gap-2 justify-between">
        <ui:switch.control />
        <ui:switch.indicator state="checked">On</ui:switch.indicator>
        <ui:switch.indicator state="unchecked">Off</ui:switch.indicator>
    </div>
</ui:switch.root>

import { mount } from 'fluid-primitives';
import { Switch } from 'fluid-primitives/switch';

mount('switch', ({ props }) => {
	const switchInstance = new Switch(props);
	switchInstance.init();
	return switchInstance;
});

Features

Based on the ARIA switch pattern
Syncs with native form elements for proper form submission
Works with Field component for form integration
Supports disabled, invalid, required, and read-only states
Full keyboard support

Installation

typo3 ui:add switch

Read more about installing Components and Primitives.

Examples

Default Checked

Set the switch to be checked by default.

Automatic updates

<ui:switch.root defaultChecked="{true}">
    <ui:switch.label>Automatic updates</ui:switch.label>
    <div class="flex items-center gap-2 justify-between">
        <ui:switch.control />
        <ui:switch.indicator state="checked">On</ui:switch.indicator>
        <ui:switch.indicator state="unchecked">Off</ui:switch.indicator>
    </div>
</ui:switch.root>

Disabled

Prevent interaction with the switch.

Airplane mode

<ui:switch.root disabled="{true}" defaultChecked="{true}">
    <ui:switch.label>Airplane mode</ui:switch.label>
    <div class="flex items-center gap-2 justify-between">
        <ui:switch.control />
        <ui:switch.indicator state="checked">On</ui:switch.indicator>
        <ui:switch.indicator state="unchecked">Off</ui:switch.indicator>
    </div>
</ui:switch.root>

With Form Field

Use the switch with the Field component for descriptions and validation.

Enable notifications

Receive product updates and occasional offers.

<ui:field.root name="marketingEmails">
    <ui:switch.root class="w-full">
        <ui:switch.label>Enable notifications</ui:switch.label>
        <div class="flex items-center gap-2 justify-between">
            <ui:switch.control />
            <ui:switch.indicator state="checked">On</ui:switch.indicator>
            <ui:switch.indicator state="unchecked">Off</ui:switch.indicator>
        </div>
    </ui:switch.root>
    <ui:field.description>Receive product updates and occasional offers.</ui:field.description>
</ui:field.root>

API Reference

The following tables cover the available props of the Fluid Primitives. For a full list of available client side props and methods, see the Zag.js Machine API.

switch.root

Groups the switch control, label, and input into one interactive label. Renders a <label> element.

Name	Description	Required	Default
`disabled`	`boolean` Whether the switch is disabled. Inherited from a surrounding field when available.	No	-
`invalid`	`boolean` If `true`, the switch is marked as invalid. Inherited from a surrounding field when available.	No	-
`required`	`boolean` If `true`, the switch input is marked as required. Inherited from a surrounding field when available.	No	-
`defaultChecked`	`boolean` The initial checked state of the switch when rendered. Use when you don't need to control the checked state of the switch.	No	false
`name`	`string` The name of the input field in a switch. Useful for form submission. Inherited from a surrounding field when available.	No	-
`form`	`string` The id of the form that the switch belongs to.	No	-
`readOnly`	`boolean` Whether the switch is read-only. Inherited from a surrounding field when available.	No	-
`value`	`string` The value of switch input. Useful for form submission.	No	1

switch.label

Displays the visible label text for the switch. Renders a <span> element.

switch.control

Displays the visual switch track. Renders a <span> element.

switch.thumb

Displays the movable thumb inside the switch track. Renders a <span> element.

switch.indicator

Displays UI for a specific switch state. Renders a <span> element.

Name	Description	Required	Default
`state`	`string` The indicator state to render. Must be `checked` or `unchecked`.	Yes	-

switch.hiddenInput

Provides the native checkbox input for form submission. Renders an <input> element.

Anatomy

<primitives:switch.root>
    <primitives:switch.control>
        <primitives:switch.thumb />
    </primitives:switch.control>
    <primitives:switch.label />
    <primitives:switch.hiddenInput />
</primitives:switch.root>