# Switch

URL: https://ark-ui.com/docs/components/switch
Source: https://raw.githubusercontent.com/chakra-ui/ark/refs/heads/main/website/src/content/pages/components/switch.mdx

A control element that allows for a binary selection.

---

<ComponentPreview id="Switch" />

## Anatomy

To set up the switch correctly, you'll need to understand its anatomy and how we name its parts.

> Each part includes a `data-part` attribute to help identify them in the DOM.

<Anatomy id="switch" />

### Design impact on the asChild property

The `Switch.Root` element of the switch is a `label` element. This is because the switch is a form control and should be
associated with a label to provide context and meaning to the user. Otherwise, the HTML and accessibility structure will
be invalid.

> If you need to use the `asChild` property, make sure that the `label` element is the direct child of the `Switch.Root`
> component.

## Examples

Learn how to use the `Switch` component in your project. Let's take a look at the most basic example:

<Example id="basic" />

### Controlled Switch

For a controlled Switch component, the state of the toggle is managed using the checked prop, and updates when the
`onCheckedChange` event handler is called:

<Example id="controlled" />

### Render Prop Usage

The Switch component also allows for a render prop, granting direct access to its internal state. This enables you to
dynamically adjust and customize aspects of the component based on its current state:

<Example id="render-prop" />

### Using the Field Component

The `Field` component helps manage form-related state and accessibility attributes of a switch. It includes handling
ARIA labels, helper text, and error text to ensure proper accessibility.

<Example id="with-field" />

### Using the Root Provider

The `RootProvider` component provides a context for the switch. It accepts the value of the `useSwitch` hook. You can
leverage it to access the component state and methods from outside the switch.

<Example id="root-provider" />

> If you're using the `RootProvider` component, you don't need to use the `Root` component.

## API Reference

### Props

**Component API Reference**

#### React

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `checked` | `boolean` | No | The controlled checked state of the switch |
| `disabled` | `boolean` | No | Whether the switch is disabled. |
| `ids` | `Partial<{ root: string; hiddenInput: string; control: string; label: string; thumb: string }>` | No | The ids of the elements in the switch. Useful for composition. |
| `invalid` | `boolean` | No | If `true`, the switch is marked as invalid. |
| `label` | `string` | No | Specifies the localized strings that identifies the accessibility elements and their states |
| `name` | `string` | No | The name of the input field in a switch
(Useful for form submission). |
| `onCheckedChange` | `(details: CheckedChangeDetails) => void` | No | Function to call when the switch is clicked. |
| `readOnly` | `boolean` | No | Whether the switch is read-only |
| `required` | `boolean` | No | If `true`, the switch input is marked as required, |
| `value` | `string | number` | No | The value of switch input. Useful for form submission. |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[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 |


**Control Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Control Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[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 |


**HiddenInput Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[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 |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseSwitchReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Thumb Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Thumb Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[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 |


#### Solid

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'label'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `checked` | `boolean` | No | The controlled checked state of the switch |
| `defaultChecked` | `boolean` | No | The initial checked state of the switch when rendered.
Use when you don't need to control the checked state of the switch. |
| `disabled` | `boolean` | No | Whether the switch is disabled. |
| `form` | `string` | No | The id of the form that the switch belongs to |
| `ids` | `Partial<{ root: string; hiddenInput: string; control: string; label: string; thumb: string }>` | No | The ids of the elements in the switch. Useful for composition. |
| `invalid` | `boolean` | No | If `true`, the switch is marked as invalid. |
| `label` | `string` | No | Specifies the localized strings that identifies the accessibility elements and their states |
| `name` | `string` | No | The name of the input field in a switch
(Useful for form submission). |
| `onCheckedChange` | `(details: CheckedChangeDetails) => void` | No | Function to call when the switch is clicked. |
| `readOnly` | `boolean` | No | Whether the switch is read-only |
| `required` | `boolean` | No | If `true`, the switch input is marked as required, |
| `value` | `string | number` | No | The value of switch input. Useful for form submission. |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[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 |


**Control Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'span'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Control Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[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 |


**HiddenInput Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'input'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'span'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[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 |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseSwitchReturn` | Yes |  |
| `asChild` | `(props: ParentProps<'label'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Thumb Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'span'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Thumb Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[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 |


#### Vue

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `checked` | `boolean` | No | The controlled checked state of the switch |
| `defaultChecked` | `boolean` | No | The initial checked state of the switch when rendered.
Use when you don't need to control the checked state of the switch. |
| `disabled` | `boolean` | No | Whether the switch is disabled. |
| `form` | `string` | No | The id of the form that the switch belongs to |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{ root: string; hiddenInput: string; control: string; label: string; thumb: string }>` | No | The ids of the elements in the switch. Useful for composition. |
| `invalid` | `boolean` | No | If `true`, the switch is marked as invalid. |
| `label` | `string` | No | Specifies the localized strings that identifies the accessibility elements and their states |
| `name` | `string` | No | The name of the input field in a switch
(Useful for form submission). |
| `readOnly` | `boolean` | No | Whether the switch is read-only |
| `required` | `boolean` | No | If `true`, the switch input is marked as required, |
| `value` | `string` | No | The value of checkbox input. Useful for form submission. |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[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 |


**Control Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Control Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[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 |


**HiddenInput Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Label Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[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 |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `SwitchApi<PropTypes>` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Thumb Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Thumb Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[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 |


#### Svelte

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'label'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `checked` | `boolean` | No | The controlled checked state of the switch |
| `defaultChecked` | `boolean` | No | The initial checked state of the switch when rendered.
Use when you don't need to control the checked state of the switch. |
| `disabled` | `boolean` | No | Whether the switch is disabled. |
| `form` | `string` | No | The id of the form that the switch belongs to |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{ root: string; hiddenInput: string; control: string; label: string; thumb: string }>` | No | The ids of the elements in the switch. Useful for composition. |
| `invalid` | `boolean` | No | If `true`, the switch is marked as invalid. |
| `label` | `string` | No | Specifies the localized strings that identifies the accessibility elements and their states |
| `name` | `string` | No | The name of the input field in a switch
(Useful for form submission). |
| `onCheckedChange` | `(details: CheckedChangeDetails) => void` | No | Function to call when the switch is clicked. |
| `readOnly` | `boolean` | No | Whether the switch is read-only |
| `ref` | `Element` | No |  |
| `required` | `boolean` | No | If `true`, the switch input is marked as required, |
| `value` | `string | number` | No | The value of switch input. Useful for form submission. |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[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 |


**Context Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `render` | `Snippet<[UseSwitchContext]>` | Yes |  |


**Control Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'span'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Control Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[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 |


**HiddenInput Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'input'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Label Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'span'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Label Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[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 |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseSwitchReturn` | Yes |  |
| `asChild` | `Snippet<[PropsFn<'label'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Thumb Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'span'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Thumb Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[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 |


### Context

These are the properties available when using `Switch.Context`, `useSwitchContext` hook or `useSwitch` hook.

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `checked` | `boolean` | Whether the switch is checked |
| `disabled` | `boolean` | Whether the switch is disabled |
| `focused` | `boolean` | 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

Complies with the [Switch WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/switch/).

### Keyboard Support

<KeyBindingsTable id="switch" />