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="{f:constant(name: 'Jramke\FluidPrimitives\Enum\SwitchIndicatorState::Checked')}">On</ui:switch.indicator>
        <ui:switch.indicator state="{f:constant(name: 'Jramke\FluidPrimitives\Enum\SwitchIndicatorState::Unchecked')}">Off</ui:switch.indicator>
    </div>
</ui:switch.root>

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

mountAll('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="{f:constant(name: 'Jramke\FluidPrimitives\Enum\SwitchIndicatorState::Checked')}">On</ui:switch.indicator>
        <ui:switch.indicator state="{f:constant(name: 'Jramke\FluidPrimitives\Enum\SwitchIndicatorState::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="{f:constant(name: 'Jramke\FluidPrimitives\Enum\SwitchIndicatorState::Checked')}">On</ui:switch.indicator>
        <ui:switch.indicator state="{f:constant(name: 'Jramke\FluidPrimitives\Enum\SwitchIndicatorState::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="{f:constant(name: 'Jramke\FluidPrimitives\Enum\SwitchIndicatorState::Checked')}">On</ui:switch.indicator>
            <ui:switch.indicator state="{f:constant(name: 'Jramke\FluidPrimitives\Enum\SwitchIndicatorState::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
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`rootId`	`string` The root ID of the component, used for hydration and identification.	No	-
`ids`	`array` The IDs of of the component parts for composition.	No	[]
`controlled`	`boolean` If true, the component is meant to be initialized manually inside another component	No	false
`class`	`string` The CSS class(es) to be applied to the component.	No	-
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]

Rendered data attributes

Attribute	Description
`data-active`	Present when active or pressed
`data-focus`	Present when focused
`data-focus-visible`	Present when focused with keyboard
`data-readonly`	Present when read-only
`data-hover`	Present when hovered
`data-disabled`	Present when disabled
`data-state`	"checked" \| "unchecked"
`data-invalid`	Present when invalid
`data-required`	Present when required

switch.label

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

Name	Description	Required	Default
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]

Rendered data attributes

Attribute	Description
`data-active`	Present when active or pressed
`data-focus`	Present when focused
`data-focus-visible`	Present when focused with keyboard
`data-readonly`	Present when read-only
`data-hover`	Present when hovered
`data-disabled`	Present when disabled
`data-state`	"checked" \| "unchecked"
`data-invalid`	Present when invalid
`data-required`	Present when required

switch.control

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

Name	Description	Required	Default
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]

Rendered data attributes

Attribute	Description
`data-active`	Present when active or pressed
`data-focus`	Present when focused
`data-focus-visible`	Present when focused with keyboard
`data-readonly`	Present when read-only
`data-hover`	Present when hovered
`data-disabled`	Present when disabled
`data-state`	"checked" \| "unchecked"
`data-invalid`	Present when invalid
`data-required`	Present when required

switch.thumb

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

Name	Description	Required	Default
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]

Rendered data attributes

Attribute	Description
`data-active`	Present when active or pressed
`data-focus`	Present when focused
`data-focus-visible`	Present when focused with keyboard
`data-readonly`	Present when read-only
`data-hover`	Present when hovered
`data-disabled`	Present when disabled
`data-state`	"checked" \| "unchecked"
`data-invalid`	Present when invalid
`data-required`	Present when required

switch.indicator

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

Name	Description	Required	Default
`state`	`Enum\SwitchIndicatorState` The indicator state to render.	Yes	-
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]

switch.hiddenInput

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

Name	Description	Required	Default
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]

Machine JavaScript API

Name	Type	Description
`checked`	`boolean`	Whether the switch is checked
`disabled`	`boolean \| undefined`	Whether the switch is disabled
`focused`	`boolean \| undefined`	Whether the switch is focused
`setChecked`	`(checked: boolean) => void`	Sets the checked state of the switch.
`toggleChecked`	`VoidFunction`	Toggles the checked state of the switch.

Accessibility

Key	Description
`SpaceEnter`	Toggle the switch

Anatomy

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

Switch

Features

Installation

Examples

Default Checked

Disabled

With Form Field

API Reference

switch.root

Rendered data attributes

switch.label

Rendered data attributes

switch.control

Rendered data attributes

switch.thumb

Rendered data attributes

switch.indicator

switch.hiddenInput

Machine JavaScript API

Accessibility

Anatomy

On this page