---
title: Switch
description: >-
  A switch control for immediate on/off settings, with controlled and
  uncontrolled checked state.
---

# Switch

## Overview

Switch is a control that lets users turn a setting on or off. Use it for immediate preference changes that take effect as soon as the switch is toggled.

```tsx
<Field label="Automatic updates" description="Periodically check for new versions">
	<Switch defaultChecked />
</Field>
```

## Usage Guidelines

- **Use for immediate settings:** Use Switch for preferences or system settings that apply immediately when changed, without requiring a separate confirmation step.
- **Use for a single binary setting:** Use Switch only when the choice is a clear enabled/disabled state, not part of a larger multi-step selection.
- **Write clear labels:** Use a short, explicit label that makes both the enabled and disabled states easy to understand without relying on surrounding context.

## API Reference

### `Switch`

| Prop              | Type                         | Default     |
| ----------------- | ---------------------------- | ----------- |
| `checked`         | `boolean`                    | `undefined` |
| `defaultChecked`  | `boolean`                    | `undefined` |
| `onCheckedChange` | `(checked: boolean) => void` | `undefined` |
| `disabled`        | `boolean`                    | `false`     |
| `required`        | `boolean`                    | `false`     |
| `name`            | `string`                     | `undefined` |
| `value`           | `string`                     | `undefined` |

## Examples

### States

```tsx
<Field label="Automatic updates">
	<Switch />
</Field>
<Field label="Smart suggestions">
	<Switch defaultChecked />
</Field>
<Field label="Shared workspace access" description="Managed by your organization." disabled>
	<Switch />
</Field>
<Field label="Critical alerts" description="Always enabled for this workspace." disabled>
	<Switch defaultChecked />
</Field>
```

### Controlled

Use the controlled API when the checked state is owned by parent state or needs to stay in sync with other UI.

```tsx
const [checked, setChecked] = useState(true);

<Field
	label="Automatic updates"
	description={checked ? "Updates are currently enabled." : "Updates are currently disabled."}
>
	<Switch checked={checked} onCheckedChange={setChecked} />
</Field>
```