---
title: Switch
description: "`Switch` is a component used to toggle between on and off states."
links:
  - style: https://github.com/yamada-ui/yamada-ui/tree/main/packages/react/src/components/switch/switch.style.ts
  - source: https://github.com/yamada-ui/yamada-ui/tree/main/packages/react/src/components/switch
  - storybook: https://yamada-ui.github.io/yamada-ui?path=/story/components-switch--basic
---

```tsx
<Switch>Basic</Switch>
```

## Usage

```tsx
import { Switch } from "@yamada-ui/react"
```

```tsx
import { Switch } from "@/components/ui"
```

```tsx
import { Switch } from "@workspaces/ui"
```

```tsx
<Switch />
```

### Change Variant

```tsx
<HStack>
  <For each={["thick", "thin"]}>
    {(variant) => (
      <Switch key={variant} variant={variant}>
        {toTitleCase(variant)}
      </Switch>
    )}
  </For>
</HStack>
```

### Change Size

```tsx
<HStack>
  <For each={["sm", "md", "lg"]}>
    {(size) => (
      <Switch key={size} size={size}>
        Size ({size})
      </Switch>
    )}
  </For>
</HStack>
```

### Change Color Scheme

```tsx
<HStack>
  <For each={["success", "warning"]}>
    {(colorScheme) => (
      <Switch key={colorScheme} colorScheme={colorScheme} defaultChecked>
        {toTitleCase(colorScheme)}
      </Switch>
    )}
  </For>
</HStack>
```

### Change Label Position

```tsx
<Switch reverse>Reverse Label</Switch>
```

### Change Shape

```tsx
<VStack>
  <For each={["square", "rounded", "circle"]}>
    {(shape) => (
      <Switch key={shape} shape={shape} defaultChecked>
        {toTitleCase(shape)}
      </Switch>
    )}
  </For>
</VStack>
```

### Disable

```tsx
<HStack>
  <Switch disabled>Disabled</Switch>
  <Switch disabled defaultChecked>
    Disabled
  </Switch>
</HStack>
```

### Read-Only

```tsx
<HStack>
  <Switch readOnly>Read Only</Switch>
  <Switch readOnly defaultChecked>
    Read Only
  </Switch>
</HStack>
```

### Customize Icon

```tsx
<Switch
  size="lg"
  icon={{ off: <MoonIcon fontSize="sm" />, on: <SunIcon fontSize="sm" /> }}
>
  Dark Mode
</Switch>
```

### Customize Label

```tsx
const id = useId()

return (
  <HStack gap="sm">
    <Text as="label" htmlFor={id} userSelect="none">
      Please Click
    </Text>
    <Switch id={id} />
  </HStack>
)
```

### Control

```tsx
const [checked, { toggle }] = useBoolean(false)

return (
  <Switch checked={checked} onChange={toggle}>
    Custom Control
  </Switch>
)
```

## Uses Components & Hooks

<Uses name="switch" />

## Props

| Prop             | Default   | Type                                                                                                                      | Description                                                          |
| ---------------- | --------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `as`             | -         | `As`                                                                                                                      | The HTML element to render.                                          |
| `asChild`        | -         | `boolean`                                                                                                                 | Merges its props onto its immediate child.                           |
| `css`            | -         | `CSSObject \| CSSObject[]`                                                                                                | The CSS object.                                                      |
| `colorScheme`    | -         | `"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...` | Set color scheme variables.                                          |
| `size`           | `"md"`    | `"lg" \| "md" \| "sm"`                                                                                                    | The size of the component.                                           |
| `variant`        | `"thick"` | `"thick" \| "thin"`                                                                                                       | The variant of the component.                                        |
| `checked`        | `false`   | `boolean`                                                                                                                 | If `true`, the switch will be checked.                               |
| `checkOnEnter`   | `true`    | `boolean`                                                                                                                 | If `true`, the switch will be checked when the Enter key is pressed. |
| `defaultChecked` | `false`   | `boolean`                                                                                                                 | If `true`, the switch will be initially checked.                     |
| `disabled`       | `false`   | `boolean`                                                                                                                 | If `true`, the field will be disabled.                               |
| `icon`           | -         | `ReactNode \| { off: ReactNode; on: ReactNode }`                                                                          | The switch icon to use.                                              |
| `id`             | -         | `string`                                                                                                                  | id assigned to input.                                                |
| `inputProps`     | -         | `HTMLStyledProps<"input">`                                                                                                | Props for switch input element.                                      |
| `invalid`        | `false`   | `boolean`                                                                                                                 | If `true`, the field will be invalid.                                |
| `labelProps`     | -         | `HTMLStyledProps<"span">`                                                                                                 | Props for switch label element.                                      |
| `name`           | -         | `string`                                                                                                                  | The HTML `name` attribute used for forms.                            |
| `onBlur`         | -         | `FocusEventHandler<HTMLInputElement>`                                                                                     | The callback invoked when the switch is blurred.                     |
| `onChange`       | -         | `ChangeEventHandler<HTMLInputElement>`                                                                                    | The callback invoked when the checked state changes.                 |
| `onFocus`        | -         | `FocusEventHandler<HTMLInputElement>`                                                                                     | The callback invoked when the switch is focused.                     |
| `readOnly`       | `false`   | `boolean`                                                                                                                 | If `true`, the field will be readonly.                               |
| `required`       | `false`   | `boolean`                                                                                                                 | If `true`, the field will be required.                               |
| `tabIndex`       | -         | `number`                                                                                                                  | The tab-index property of the underlying input element.              |
| `value`          | -         | `Y`                                                                                                                       | The value to be used in the switch input.                            |

## Accessibility

The `Switch` follows the [WAI-ARIA - Switch Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/switch/) for accessibility.

### Keyboard Navigation

| Key     | Description                                                            | State |
| ------- | ---------------------------------------------------------------------- | ----- |
| `Tab`   | Focuses on a switch that is not disabled.                              | -     |
| `Space` | Toggles the state of the focused switch.                               | -     |
| `Enter` | Toggles the state of the focused switch when `checkOnEnter` is `true`. | -     |

### ARIA Roles and Attributes

| Component | Roles and Attributes | Usage                                                                                                                                                          |
| --------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Switch`  | `role="switch"`      | Indicates that this is a switch.                                                                                                                               |
|           | `aria-checked`       | Sets to `"true"` if the switch is on, and `"false"` if it is off.                                                                                              |
|           | `aria-describedby`   | If `Switch` is within a `Field.Root` and `Field.Root` has an `errorMessage`, `helperMessage`, or a `Field.ErrorMessage`, `Field.HelperMessage`, sets its `id`. |
|           | `aria-disabled`      | Sets to `"true"` if `disabled` is set.                                                                                                                         |
|           | `aria-invalid`       | Sets to `"true"` if `invalid` is set.                                                                                                                          |
|           | `aria-readonly`      | Sets to `"true"` if `readOnly` is set.                                                                                                                         |
|           | `aria-required`      | Sets to `"true"` if `required` is set.                                                                                                                         |