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>

Features

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

Anatomy

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

Installation

typo3 ui:add switch

Read more about installing Components and Primitives.

Examples

Start checked

Set defaultChecked to render the switch on.

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>

Disable the switch

Set disabled to lock the switch in its current state.

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>

Add helper text and validation

Wrap the switch in a Field for a helper text, validation messages and the name it submits under.

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.helperText>Receive product updates and occasional offers.</ui:field.helperText>
</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
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`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	[]
`autoMount`	`boolean` Whether the client initializes the component on its own. Set it to false to mount it yourself with `mount()`	No	true
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-switch-root`	<uid>
`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
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`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	-

Rendered data attributes

Attribute	Description
`data-switch-label`	<uid>
`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
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`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	-

Rendered data attributes

Attribute	Description
`data-switch-control`	<uid>
`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
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`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	-

Rendered data attributes

Attribute	Description
`data-switch-thumb`	<uid>
`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	-
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`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	-

switch.hiddenInput

Provides the native checkbox input for form submission. Renders an <input> element, with the empty-value input that submits '' while the switch is off in front of it.

Name	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`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	-

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.
`getRootState`	`() => RootState`	Returns the state of the switch

Accessibility

Key	Description
`SpaceEnter`	Toggle the switch