Switch

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

Airplane mode

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

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

pnpm add akar

yarn add akar

npm install akar

bun add akar

Anatomy

Import all parts and piece them together.

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

Prop	Default	Type
`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. Read our 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`.

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

Slot (default)	Payload
`modelValue`	`T` Current value
`checked`	`boolean` Whether the switch is checked

SwitchRoot.vue source

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.

Prop	Default	Type
`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. Read our Composition guide for more details.

SwitchThumb.vue source

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.

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

Keyboard Interactions

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

Stepper

A set of steps that are used to indicate progress through a multi-step process.

Tabs

A set of layered sections of content—known as tab panels—that are displayed one at a time.