---
title: Switch
description: Toggle switch for on/off states.
icon: toggle-on
---

import { ComponentPreview } from "/snippets/component-preview.mdx";

Switches provide a visual toggle for binary states, offering an alternative to checkboxes.

## Basic Usage

<ComponentPreview json={{"view":{"name":"switch_5","type":"Switch","label":"Enable notifications","checked":false,"size":"default","disabled":false,"required":false},"state":{"switch_5":false}}} playground="ZnJvbSBwcmVmYWJfdWkuY29tcG9uZW50cyBpbXBvcnQgU3dpdGNoCgpTd2l0Y2gobGFiZWw9IkVuYWJsZSBub3RpZmljYXRpb25zIikK">
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import Switch

Switch(label="Enable notifications")
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "name": "switch_5",
    "type": "Switch",
    "label": "Enable notifications",
    "checked": false,
    "size": "default",
    "disabled": false,
    "required": false
  },
  "state": {"switch_5": false}
}
```
</CodeGroup>
</ComponentPreview>

## Checked State

<ComponentPreview json={{"view":{"name":"switch_6","type":"Switch","label":"Dark mode","checked":true,"size":"default","disabled":false,"required":false},"state":{"switch_6":true}}} playground="ZnJvbSBwcmVmYWJfdWkuY29tcG9uZW50cyBpbXBvcnQgU3dpdGNoCgpTd2l0Y2gobGFiZWw9IkRhcmsgbW9kZSIsIGNoZWNrZWQ9VHJ1ZSkK">
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import Switch

Switch(label="Dark mode", checked=True)
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "name": "switch_6",
    "type": "Switch",
    "label": "Dark mode",
    "checked": true,
    "size": "default",
    "disabled": false,
    "required": false
  },
  "state": {"switch_6": true}
}
```
</CodeGroup>
</ComponentPreview>

## Sizes

Switches come in two sizes:

<ComponentPreview json={{"view":{"cssClass":"gap-4 w-fit mx-auto","type":"Column","children":[{"name":"switch_7","type":"Switch","label":"Default size","checked":true,"size":"default","disabled":false,"required":false},{"name":"switch_8","type":"Switch","label":"Small size","checked":true,"size":"sm","disabled":false,"required":false}]},"state":{"switch_7":true,"switch_8":true}}} playground="ZnJvbSBwcmVmYWJfdWkuY29tcG9uZW50cyBpbXBvcnQgKAogICAgQ29sdW1uLAogICAgU3dpdGNoLAopCgp3aXRoIENvbHVtbihnYXA9NCwgY3NzX2NsYXNzPSJ3LWZpdCBteC1hdXRvIik6CiAgICBTd2l0Y2gobGFiZWw9IkRlZmF1bHQgc2l6ZSIsIGNoZWNrZWQ9VHJ1ZSkKICAgIFN3aXRjaChsYWJlbD0iU21hbGwgc2l6ZSIsIHNpemU9InNtIiwgY2hlY2tlZD1UcnVlKQo=">
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import (
    Column,
    Switch,
)

with Column(gap=4, css_class="w-fit mx-auto"):
    Switch(label="Default size", checked=True)
    Switch(label="Small size", size="sm", checked=True)
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "cssClass": "gap-4 w-fit mx-auto",
    "type": "Column",
    "children": [
      {
        "name": "switch_7",
        "type": "Switch",
        "label": "Default size",
        "checked": true,
        "size": "default",
        "disabled": false,
        "required": false
      },
      {
        "name": "switch_8",
        "type": "Switch",
        "label": "Small size",
        "checked": true,
        "size": "sm",
        "disabled": false,
        "required": false
      }
    ]
  },
  "state": {"switch_7": true, "switch_8": true}
}
```
</CodeGroup>
</ComponentPreview>

## With Actions

The `on_change` parameter runs actions when the switch is toggled. The `$event` variable is `true` when switched on, `false` when off. Here, toggling the switch updates a separate status message:

<ComponentPreview json={{"view":{"cssClass":"gap-4 w-fit mx-auto","type":"Column","children":[{"name":"notifications","type":"Switch","label":"Enable notifications","checked":false,"size":"default","disabled":false,"required":false,"onChange":{"action":"setState","key":"status","value":"{{ $event ? 'Notifications enabled' : 'Notifications disabled' }}"}},{"cssClass":"text-muted-foreground","content":"{{ status | default:'Toggle the switch' }}","type":"Text"}]},"state":{"notifications":false}}} playground=" ">
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import Column, Switch, Text
from prefab_ui.actions import SetState
from prefab_ui.rx import Rx

event = Rx("$event")
status = Rx("status")

with Column(gap=4, css_class="w-fit mx-auto"):
    Switch(
        label="Enable notifications",
        name="notifications",
        on_change=SetState(
            "status",
            event.then("Notifications enabled", "Notifications disabled"),
        ),
    )
    Text(
        status.default("Toggle the switch"),
        css_class="text-muted-foreground",
    )
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "cssClass": "gap-4 w-fit mx-auto",
    "type": "Column",
    "children": [
      {
        "name": "notifications",
        "type": "Switch",
        "label": "Enable notifications",
        "checked": false,
        "size": "default",
        "disabled": false,
        "required": false,
        "onChange": {
          "action": "setState",
          "key": "status",
          "value": "{{ $event ? 'Notifications enabled' : 'Notifications disabled' }}"
        }
      },
      {
        "cssClass": "text-muted-foreground",
        "content": "{{ status | default:'Toggle the switch' }}",
        "type": "Text"
      }
    ]
  },
  "state": {"notifications": false}
}
```
</CodeGroup>
</ComponentPreview>

## Disabled State

<ComponentPreview json={{"view":{"cssClass":"gap-3 w-fit mx-auto","type":"Column","children":[{"name":"switch_9","type":"Switch","label":"Enabled switch","checked":false,"size":"default","disabled":false,"required":false},{"name":"switch_10","type":"Switch","label":"Disabled off","checked":false,"size":"default","disabled":true,"required":false},{"name":"switch_11","type":"Switch","label":"Disabled on","checked":true,"size":"default","disabled":true,"required":false}]},"state":{"switch_9":false,"switch_10":false,"switch_11":true}}} playground="ZnJvbSBwcmVmYWJfdWkuY29tcG9uZW50cyBpbXBvcnQgKAogICAgQ29sdW1uLAogICAgU3dpdGNoLAopCgp3aXRoIENvbHVtbihnYXA9MywgY3NzX2NsYXNzPSJ3LWZpdCBteC1hdXRvIik6CiAgICBTd2l0Y2gobGFiZWw9IkVuYWJsZWQgc3dpdGNoIikKICAgIFN3aXRjaChsYWJlbD0iRGlzYWJsZWQgb2ZmIiwgZGlzYWJsZWQ9VHJ1ZSkKICAgIFN3aXRjaChsYWJlbD0iRGlzYWJsZWQgb24iLCBjaGVja2VkPVRydWUsIGRpc2FibGVkPVRydWUpCg==">
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import (
    Column,
    Switch,
)

with Column(gap=3, css_class="w-fit mx-auto"):
    Switch(label="Enabled switch")
    Switch(label="Disabled off", disabled=True)
    Switch(label="Disabled on", checked=True, disabled=True)
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "cssClass": "gap-3 w-fit mx-auto",
    "type": "Column",
    "children": [
      {
        "name": "switch_9",
        "type": "Switch",
        "label": "Enabled switch",
        "checked": false,
        "size": "default",
        "disabled": false,
        "required": false
      },
      {
        "name": "switch_10",
        "type": "Switch",
        "label": "Disabled off",
        "checked": false,
        "size": "default",
        "disabled": true,
        "required": false
      },
      {
        "name": "switch_11",
        "type": "Switch",
        "label": "Disabled on",
        "checked": true,
        "size": "default",
        "disabled": true,
        "required": false
      }
    ]
  },
  "state": {"switch_9": false, "switch_10": false, "switch_11": true}
}
```
</CodeGroup>
</ComponentPreview>

## Reading the Value

Use `.rx` to get a reactive reference to the switch's boolean state. The `.then()` pipe converts `true`/`false` into display-friendly strings:

<ComponentPreview json={{"view":{"cssClass":"gap-4 items-center","type":"Row","children":[{"name":"switch_12","type":"Switch","label":"Auto-save to the Guide","checked":true,"size":"default","disabled":false,"required":false},{"type":"Label","text":"Auto-save:"},{"name":"input_17","type":"Input","inputType":"text","value":"{{ switch_12 ? 'On' : 'Off' }}","disabled":false,"readOnly":true,"required":false}]},"state":{"switch_12":true}}} playground="ZnJvbSBwcmVmYWJfdWkuY29tcG9uZW50cyBpbXBvcnQgSW5wdXQsIExhYmVsLCBSb3csIFN3aXRjaAoKd2l0aCBSb3coZ2FwPTQsIGFsaWduPSJjZW50ZXIiKToKICAgIHN3ID0gU3dpdGNoKGxhYmVsPSJBdXRvLXNhdmUgdG8gdGhlIEd1aWRlIiwgY2hlY2tlZD1UcnVlKQogICAgTGFiZWwoIkF1dG8tc2F2ZToiKQogICAgSW5wdXQodmFsdWU9c3cucngudGhlbigiT24iLCAiT2ZmIiksIHJlYWRfb25seT1UcnVlKQo=">
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import Input, Label, Row, Switch

with Row(gap=4, align="center"):
    sw = Switch(label="Auto-save to the Guide", checked=True)
    Label("Auto-save:")
    Input(value=sw.rx.then("On", "Off"), read_only=True)
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "cssClass": "gap-4 items-center",
    "type": "Row",
    "children": [
      {
        "name": "switch_12",
        "type": "Switch",
        "label": "Auto-save to the Guide",
        "checked": true,
        "size": "default",
        "disabled": false,
        "required": false
      },
      {"type": "Label", "text": "Auto-save:"},
      {
        "name": "input_17",
        "type": "Input",
        "inputType": "text",
        "value": "{{ switch_12 ? 'On' : 'Off' }}",
        "disabled": false,
        "readOnly": true,
        "required": false
      }
    ]
  },
  "state": {"switch_12": true}
}
```
</CodeGroup>
</ComponentPreview>

Toggle the switch and the input updates to reflect the current state.

## API Reference

<Card icon="code" title="Switch Parameters">

<ParamField body="label" type="str | None" default="None">
  Label text displayed next to the switch.
</ParamField>

<ParamField body="checked" type="bool" default="False">
  Whether the switch is on.
</ParamField>

<ParamField body="size" type="str" default="default">
  Switch size: `"default"`, `"sm"`.
</ParamField>

<ParamField body="name" type="str | None" default="None">
  State key for the switch's checked state. Auto-generated if not provided. Use `.rx` to reference the switch's boolean state in other components without specifying the name explicitly.
</ParamField>

<ParamField body="disabled" type="bool" default="False">
  Whether the switch is non-interactive.
</ParamField>

<ParamField body="required" type="bool" default="False">
  Whether a selection is required for form submission.
</ParamField>

<ParamField body="on_change" type="Action | list[Action] | None" default="None">
  Action(s) to execute when toggled. `$event` is `true` when on, `false` when off.
</ParamField>

<ParamField body="css_class" type="str | None" default="None">
  Additional Tailwind CSS classes appended to the component's built-in styles.
</ParamField>
</Card>

## Protocol Reference

```json Switch
{
  "type": "Switch",
  "label?": "string",
  "checked?": false,
  "size?": "sm | default",
  "name?": "string",
  "disabled?": false,
  "required?": false,
  "onChange?": "Action | Action[]",
  "cssClass?": "string"
}
```

For the complete protocol schema, see [Switch](/protocol/switch).
