Toggle

A two-state button that can be either on or off.

<script setup lang="ts">
import { Toggle } from 'akar';
import { ref } from 'vue';
import './styles.css';

const toggleState = ref(false);
</script>

<template>
  <div class="akar-demo akar-demo-Toggle">
    <Toggle
      v-model="toggleState"
      aria-label="Toggle italic"
      class="Toggle"
    >
      <PIcon name="i-lucide-italic" />
    </Toggle>
  </div>
</template>

@import '../_colors/black-alpha.css';
@import '../_colors/mauve.css';
@import '../_colors/grass.css';

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

  .Toggle {
    background-color: white;
    color: var(--mauve-11);
    height: 35px;
    width: 35px;
    border-radius: 4px;
    display: flex;
    font-size: 15px;
    line-height: 1;
    align-items: center;
    justify-content: center;
    box-shadow: 0 2px 10px var(--black-a7);
  }
  .Toggle:hover {
    background-color: var(--grass-3);
  }
  .Toggle[data-state='on'] {
    background-color: var(--grass-6);
    color: var(--grass-12);
  }
  .Toggle:focus {
    box-shadow: 0 0 0 2px black;
  }
}

Features

Full keyboard navigation.
Can be controlled or uncontrolled.

Installation

Install the component from your command line.

pnpm add akar

yarn add akar

npm install akar

bun add akar

Anatomy

Import the component.

<script setup>
import { Toggle } from 'akar';
</script>

<template>
  <Toggle />
</template>

API Reference

Root

The toggle.

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`		`boolean` The pressed state of the toggle when it is initially rendered. Use when you do not need to control its open state.
`disabled`	`false`	`boolean` When `true`, prevents the user from interacting with the toggle.
`modelValue`		`boolean \| null` The controlled pressed state of the toggle. 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.

Event	Payload
`update:modelValue`	`value: boolean` Event handler called when the value of the toggle changes.

Slot (default)	Payload
`modelValue`	`boolean` Current value
`state`	`"on" \| "off"` Current state
`pressed`	`boolean` Current pressed state
`disabled`	`boolean` Current disabled state

Toggle.vue source

Data attribute	Value
`[data-state]`	`"on" \| "off"`
`[data-disabled]`	Present when disabled

Accessibility

Keyboard Interactions

Key	Description
`Space`	Activates/deactivates the toggle.
`Enter`	Activates/deactivates the toggle.

Toast

A succinct message that is displayed temporarily.

Toggle Group

A set of two-state buttons that can be toggled on or off.