Toggle
newA two-state button with Button's variants, colours and sizes, and its own look when on.
Open Props in the corner of the example to try variant, activeVariant, color, size and disabled. variant and color style the toggle while it is off, activeVariant and activeColor while it is on, from Button's variants and colours; by default a toggle is transparent and neutral, and fills softly when on. size takes Button's sizes, the icon-* ones for a lone icon.
Installation
Usage
<script setup lang="ts">
import { Bold } from '@lucide/vue'
import { Toggle } from '@/components/ui/toggle'
const bold = ref(false)
</script>
<template>
<Toggle v-model="bold" size="icon-md" aria-label="Bold">
<Bold />
</Toggle>
</template>
Toggle is Reka UI's toggle styled like a Button. It is a button with aria-pressed, and v-model binds whether it is on. For a set of toggles, use Toggle Group.
Examples
Active look
A toggle can change its look when it's on. Any pair works: an outline toggle that turns solid primary, or soft warning for a favourite.
Using a custom colour as activeColor? Add a second selector to its rule so it also applies when the toggle is on:
@layer base {
[data-slot][data-color='pro'],
[data-slot][aria-pressed='true'][data-active-color='pro'] {
--tone: var(--pro);
/* … */
}
}
With text
API Reference
class is merged over the toggle's classes with tailwind-merge.
Toggle
| Prop | Default | Type and description |
|---|---|---|
| defaultValue | — | booleanWhether it starts on when |
| modelValue | — | boolean | nullWhether it is on, bound with |
| disabled | false | booleanStops it from being pressed and draws it in the disabled colours, on or off. |
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | "button" | AsTag | ComponentThe element or component to render. |
| name | — | stringThe field name, for submitting its state with a form. |
| required | — | booleanMarks the form field as required. |
| variant | "ghost" | "ghost" | "soft" | "solid" | "subtle" | "outline" | "link" | nullButton's variant, for the toggle while it is off. |
| activeVariant | "soft" | "ghost" | "soft" | "solid" | "subtle" | "outline" | "link" | nullButton's variant, for the toggle while it is on. |
| color | "neutral" | ButtonColor | (string & {})Button's colour, or any colour of your theme, for the toggle while it is off. |
| activeColor | — | ButtonColor | (string & {})The colour while it is on. Follows |
| size | "md" | ButtonSizeButton's sizes. The |
| Event | Payload and description |
|---|---|
| update:modelValue | [value: boolean]Fires when it is pressed, with whether it is now on. |
| Slot | Scope and description |
|---|---|
| default | { modelValue: boolean; state: DataState; pressed: boolean; disabled: boolean; }The label and icons. Receives |
Props
- defaultValue
booleanWhether it starts on whenv-modelis not used.- modelValue
boolean | nullWhether it is on, bound withv-model.- disabled
false booleanStops it from being pressed and draws it in the disabled colours, on or off.- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
"button" AsTag | ComponentThe element or component to render.- name
stringThe field name, for submitting its state with a form.- required
booleanMarks the form field as required.- variant
"ghost" "ghost" | "soft" | "solid" | "subtle" | "outline" | "link" | nullButton's variant, for the toggle while it is off.ghostby default.- activeVariant
"soft" "ghost" | "soft" | "solid" | "subtle" | "outline" | "link" | nullButton's variant, for the toggle while it is on.softby default.- color
"neutral" ButtonColor | (string & {})Button's colour, or any colour of your theme, for the toggle while it is off.neutralby default.- activeColor
ButtonColor | (string & {})The colour while it is on. Followscolorwhen not set.- size
"md" ButtonSizeButton's sizes. Theicon-*sizes make a square toggle for an icon.
Emits
- update:modelValue
[value: boolean]Fires when it is pressed, with whether it is now on.
Slots
- default
{ modelValue: boolean; state: DataState; pressed: boolean; disabled: boolean; }The label and icons. ReceivesmodelValue,pressed,stateanddisabled.
Data attributes
| data-slot | Attributes | Description |
|---|---|---|
| toggle | data-state, data-variant, data-color, data-active-color, data-size, data-disabled | The button. data-state is on or off; while it is on, data-active-color takes over the colour. |