# Switch

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

**Reference:** [View Source](https://github.com/jramke/fluid-primitives/tree/main/Resources/Private/Primitives/Switch) · [Zag.js Docs](https://zagjs.com/components/react/switch)

**Switch.html**

```html
<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>

```

**Switch.ts**

```ts
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

```bash
typo3 ui:add switch
```

Or copy the files manually from GitHub (https://github.com/jramke/fluid-primitives.com/tree/main/packages/docs/Resources/Private/Registry/Switch) into your project.

Read more about installing [Components and Primitives](/docs/core-concepts/primitives.md).

## Examples

### Default Checked

Set the switch to be checked by default.

**Switch.html**

```html
<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.

**Switch.html**

```html
<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.

**Switch.html**

```html
<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

### switch.root

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

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `disabled` | `boolean` | No | `-` | Whether the switch is disabled. Inherited from a surrounding field when available. |
| `invalid` | `boolean` | No | `-` | If `true`, the switch is marked as invalid. Inherited from a surrounding field when available. |
| `required` | `boolean` | No | `-` | If `true`, the switch input is marked as required. Inherited from a surrounding field when available. |
| `defaultChecked` | `boolean` | No | `false` | The initial checked state of the switch when rendered. Use when you don't need to control the checked state of the switch. |
| `name` | `string` | No | `-` | The name of the input field in a switch. Useful for form submission. Inherited from a surrounding field when available. |
| `form` | `string` | No | `-` | The id of the form that the switch belongs to. |
| `readOnly` | `boolean` | No | `-` | Whether the switch is read-only. Inherited from a surrounding field when available. |
| `value` | `string` | No | `1` | The value of switch input. Useful for form submission. |
| `asChild` | `boolean` | No | `-` | If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. |
| `rootId` | `string` | No | `-` | The root ID of the component, used for hydration and identification. |
| `ids` | `array` | No | `[]` | The IDs of of the component parts for composition. |
| `controlled` | `boolean` | No | `false` | If true, the component is meant to be initialized manually inside another component |
| `class` | `string` | No | `-` | The CSS class(es) to be applied to the component. |
| `attributes` | `array` | No | `[]` | Additional attributes that should be rendered on the component where ui:attributes is used. |

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

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

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

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

### switch.hiddenInput

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

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

### 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 |
| --- | --- |
| `Space` `Enter`  | Toggle the switch |

## Anatomy

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