# 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

<Anatomy id="switch" />

```tsx
<Switch.Root>
  <Switch.Control>
    <Switch.Thumb />
  </Switch.Control>
  <Switch.Label />
  <Switch.HiddenInput />
</Switch.Root>
```

## Examples

**Example: basic**

```ripple
import { Switch } from 'ark-ripple/switch';
import styles from 'styles/switch.module.css';

export component Basic() {
  <Switch.Root class={styles.Root}>
    <Switch.Control class={styles.Control}>
      <Switch.Thumb class={styles.Thumb} />
    </Switch.Control>
    <Switch.Label class={styles.Label}>{'Label'}</Switch.Label>
    <Switch.HiddenInput />
  </Switch.Root>
}

```

### Controlled

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: controlled**

```ripple
import { Switch } from 'ark-ripple/switch';
import { track } from 'ripple';
import styles from 'styles/switch.module.css';

export component Controlled() {
  let checked = track(false);

  <Switch.Root
    class={styles.Root}
    {checked}
    onCheckedChange={(e) => {
      @checked = e.checked;
    }}
  >
    <Switch.Control class={styles.Control}>
      <Switch.Thumb class={styles.Thumb} />
    </Switch.Control>
    <Switch.Label class={styles.Label}>{'Label'}</Switch.Label>
    <Switch.HiddenInput />
  </Switch.Root>
}

```

### Root Provider

An alternative way to control the switch is to use the `RootProvider` component and the `useSwitch` hook. This way you
can access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { Switch, useSwitch } from 'ark-ripple/switch';
import button from 'styles/button.module.css';
import styles from 'styles/switch.module.css';

export component RootProvider() {
  const api = useSwitch();

  <div class="stack">
    <button
      class={button.Root}
      onClick={() => {
        @api.toggleChecked();
      }}
    >
      {'Toggle'}
    </button>

    <Switch.RootProvider class={styles.Root} value={api}>
      <Switch.Control class={styles.Control}>
        <Switch.Thumb class={styles.Thumb} />
      </Switch.Control>
      <Switch.Label class={styles.Label}>{'Label'}</Switch.Label>
      <Switch.HiddenInput />
    </Switch.RootProvider>
  </div>
}

```

### Field

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: with-field**

```ripple
import { Field } from 'ark-ripple/field';
import { Switch } from 'ark-ripple/switch';
import field from 'styles/field.module.css';
import styles from 'styles/switch.module.css';

export component WithField() {
  <Field.Root class={field.Root}>
    <Switch.Root class={styles.Root}>
      <Switch.Control class={styles.Control}>
        <Switch.Thumb class={styles.Thumb} />
      </Switch.Control>
      <Switch.Label class={styles.Label}>{'Label'}</Switch.Label>
      <Switch.HiddenInput />
    </Switch.Root>
    <Field.HelperText class={field.HelperText}>{'Additional Info'}</Field.HelperText>
    <Field.ErrorText class={field.ErrorText}>{'Error Info'}</Field.ErrorText>
  </Field.Root>
}

```

### Context

Access the switch's state with `Switch.Context` or the `useSwitchContext` hook. This lets you customize the component
based on its current state:

**Example: context**

```ripple
import { Switch } from 'ark-ripple/switch';
import styles from 'styles/switch.module.css';

export component Context() {
  <Switch.Root class={styles.Root}>
    <Switch.Control class={styles.Control}>
      <Switch.Thumb class={styles.Thumb} />
    </Switch.Control>
    <Switch.Context>
      component children({ context }) {
        <Switch.Label class={styles.Label}>
          {'Feature is '}
          {@context.checked ? 'enabled' : 'disabled'}
        </Switch.Label>
      }
    </Switch.Context>
    <Switch.HiddenInput />
  </Switch.Root>
}

```

## Guides

### asChild

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.

## API Reference

### Props

**Component API Reference**

**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 |


### Context

**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" />