---
title: "Switch"
description: "A control that allows the user to toggle between checked and not checked."
canonical_url: "https://vinicunca.dev/akar/components/switch"
---
# Switch

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

```vue [index.vue]
<script setup lang="ts">
import { SwitchRoot, SwitchThumb } from 'akar'
import { ref } from 'vue'
import './styles.css'

const switchState = ref(false)
</script>

<template>
  <div class="akar-demo akar-demo-Switch">
    <div :style="{ display: 'flex', alignItems: 'center' }">
        <label
          class="Label"
          for="airplane-mode"
        >
          Airplane mode
        </label>
        <SwitchRoot
          id="airplane-mode"
          v-model="switchState"
          class="SwitchRoot"
        >
          <SwitchThumb
            class="SwitchThumb"
          />
        </SwitchRoot>
      </div>
  </div>
</template>
```

```css [styles.css]
@import '../_colors/black-alpha.css';

@scope (.akar-demo-Switch) {
/* reset */
button {
  all: unset;
}

.SwitchRoot {
  width: 42px;
  height: 25px;
  background-color: var(--black-a9);
  border-radius: 9999px;
  position: relative;
  box-shadow: 0 2px 10px var(--black-a7);
  -webkit-tap-highlight-color: rgba(0, 0, 0, 0);
}
.SwitchRoot:focus {
  box-shadow: 0 0 0 2px black;
}
.SwitchRoot[data-state='checked'] {
  background-color: black;
}

.SwitchThumb {
  display: block;
  width: 21px;
  height: 21px;
  background-color: white;
  border-radius: 9999px;
  box-shadow: 0 2px 2px var(--black-a7);
  transition: transform 100ms;
  transform: translateX(2px);
  will-change: transform;
}
.SwitchThumb[data-state='checked'] {
  transform: translateX(19px);
}

.Label {
  color: white;
  font-size: 15px;
  line-height: 1;
}
}
```

## Features

- Full keyboard navigation.
- Can be controlled or uncontrolled.
- Supports custom true/false values.

## Installation

Install the component from your command line.

```bash [pnpm]
pnpm add akar
```

```bash [yarn]
yarn add akar
```

```bash [npm]
npm install akar
```

```bash [bun]
bun add akar
```

## Anatomy

Import all parts and piece them together.

```vue
<script setup>
import { SwitchRoot, SwitchThumb } from 'akar';
</script>

<template>
  <SwitchRoot>
    <SwitchThumb />
  </SwitchRoot>
</template>
```

## 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.

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `as` | `"button"` | `AsTag \| Component` | The element or component this component should render as. Can be overwritten by `asChild`. |
| `asChild` |  | `boolean` | Change the default rendered element for the one passed as a child, merging their props and behavior.<br><br>Read our [Composition](https://vinicunca.dev/akar/guides/composition) guide for more details. |
| `defaultValue` |  | `T` | The state of the switch when it is initially rendered. Use when you do not need to control its state. |
| `disabled` |  | `boolean` | When `true`, prevents the user from interacting with the switch. |
| `falseValue` | `(() => false) as unknown as undefined` | `T` | The value used when the switch is off. Defaults to `false`. |
| `id` |  | `string` |  |
| `modelValue` |  | `null \| T` | The controlled state of the switch. Can be bind as `v-model`. |
| `name` |  | `string` | The name of the field. Submitted with its owning form as part of a name/value pair. |
| `required` |  | `boolean` | When `true`, indicates that the user must set the value before the owning form can be submitted. |
| `trueValue` | `(() => true) as unknown as undefined` | `T` | The value used when the switch is on. Defaults to `true`. |
| `value` | `"on"` | `string` | The value given as data when submitted with a `name`. |

**Events**

| Event | Payload | Description |
| --- | --- | --- |
| `update:modelValue` | `payload: T` | Event handler called when the value of the switch changes. |

**Slots**

| Slot | Payload | Description |
| --- | --- | --- |
| `modelValue` | `T` | Current value |
| `checked` | `boolean` | Whether the switch is checked |

[SwitchRoot.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/Switch/SwitchRoot.vue)

| Data attribute | Value |
| --- | --- |
| `[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.

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `as` | `"span"` | `AsTag \| Component` | The element or component this component should render as. Can be overwritten by `asChild`. |
| `asChild` |  | `boolean` | Change the default rendered element for the one passed as a child, merging their props and behavior.<br><br>Read our [Composition](https://vinicunca.dev/akar/guides/composition) guide for more details. |

[SwitchThumb.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/Switch/SwitchThumb.vue)

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

## Examples

### Custom Values

Use the `trueValue` and `falseValue` props to specify custom values for the on and off states instead of the default `true`/`false`.

```vue
<script setup>
import { SwitchRoot, SwitchThumb } from 'akar'
import { ref } from 'vue'

// With string values
const status = ref('inactive')

// With number values
const enabled = ref(0)
</script>

<template>
  <!-- String values -->
  <SwitchRoot v-model="status" true-value="active" false-value="inactive">
    <SwitchThumb />
  </SwitchRoot>
  Status: {{ status }} <!-- "active" or "inactive" -->

  <!-- Number values -->
  <SwitchRoot v-model="enabled" :true-value="1" :false-value="0">
    <SwitchThumb />
  </SwitchRoot>
  Enabled: {{ enabled }} <!-- 1 or 0 -->
</template>
```

## Accessibility

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

### Keyboard Interactions

| Key | Description |
| --- | --- |
| <kbd>Space</kbd> | Toggles the component's state. |
| <kbd>Enter</kbd> | Toggles the component's state. |

---

- [ARIA](https://www.w3.org/WAI/ARIA/apg/patterns/switch)
- [GitHub](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/Switch)
- [npm](https://www.npmjs.com/package/akar)


## Sitemap

See the full [sitemap](https://vinicunca.dev/sitemap.md) for all pages.