> Native Solid 2 fork. Original documentation and designs © WorkOS; historical posts retain their original context.

# Switch

A control that allows the user to toggle between checked and not checked.

## Features

- Full keyboard navigation.

- Can be controlled or uncontrolled.

## Anatomy

Import all parts and piece them together.

```jsx
import { Switch } from "@radix-solid/primitives";

export default () => <Switch.Root>

		<Switch.Thumb />

	</Switch.Root>;
```

## API Reference

### Root

Contains all the parts of a switch. An `input` will also render when used within a `form` to ensure events propagate correctly.

| Prop                                                                                                                                                                    | Type       | Default |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------- |
| `asChild`Render through a single-target factory, merging props and behavior with the chosen host. Read our [Composition](../guides/composition) guide for more details. | `boolean`  | `false` |
| `defaultChecked`The state of the switch when it is initially rendered. Use when you do not need to control its state.                                                   | `boolean`  | —       |
| `checked`The controlled state of the switch. Must be used in conjunction with `onCheckedChange`.                                                                        | `boolean`  | —       |
| `onCheckedChange`Event handler called when the state of the switch changes.                                                                                             | `function` | —       |
| `disabled`When `true`, prevents the user from interacting with the switch.                                                                                              | `boolean`  | —       |
| `required`When `true`, indicates that the user must check the switch before the owning form can be submitted.                                                           | `boolean`  | —       |
| `name`The name of the switch. Submitted with its owning form as part of a name/value pair.                                                                              | `string`   | —       |
| `value`The value given as data when submitted with a `name`.                                                                                                            | `string`   | `on`    |

| Data attribute    | Values                     |
| ----------------- | -------------------------- |
| `[data-state]`    | `"checked" \| "unchecked"` |
| `[data-disabled]` | Present when disabled      |

### Thumb

The thumb that is used to visually indicate whether the switch is on or off.

| Prop                                                                                                                                                                    | Type      | Default |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- |
| `asChild`Render through a single-target factory, merging props and behavior with the chosen host. Read our [Composition](../guides/composition) guide for more details. | `boolean` | `false` |

| Data attribute    | Values                     |
| ----------------- | -------------------------- |
| `[data-state]`    | `"checked" \| "unchecked"` |
| `[data-disabled]` | Present when disabled      |

## Examples

### Decoupling the hidden input

By default, `Switch.Root` renders a visually hidden `input` for form submission. To recompose, move, or exclude that input, you can build the switch from its lower-level parts instead.

> **Important:** These parts are unstable and prefixed with `unstable_`, so their API may change in a future release.

- `Switch.unstable_Provider` provides the switch state and accepts the form-related props (`name`, `value`, `checked`, `defaultChecked`, `required`, `disabled`, `onCheckedChange`).
- `Switch.unstable_Trigger` is the interactive button that wraps `Switch.Thumb`.
- `Switch.unstable_BubbleInput` is the visually hidden input that `Switch.Root` renders by default. Omit it when you don't need form submission.

```jsx
import { Switch } from "@radix-solid/primitives";

export default () => <Switch.unstable_Provider name="airplane-mode">

		<Switch.unstable_Trigger>

			<Switch.Thumb />

		</Switch.unstable_Trigger>

		{/* The hidden input can be omitted if you don't need form submission */}

		<Switch.unstable_BubbleInput />

	</Switch.unstable_Provider>;
```

## Accessibility

Adheres to the [`switch` role requirements](https://www.w3.org/WAI/ARIA/apg/patterns/switch).

### Keyboard Interactions

| Key     | Description                    |
| ------- | ------------------------------ |
| `Space` | Toggles the component's state. |
| `Enter` | Toggles the component's state. |