Switch
A toggle control for binary or custom on/off values.
Switch renders a role="switch" button with custom model values, labels, descriptions, and track/thumb slots.
Anatomy
#thumb: Sliding indicator inside the track.#label: Label beside the switch.#description: Supplementary text below the label.
Usage
Examples
Custom thumb
Use #thumb to replace the sliding indicator while keeping switch behavior.
@layer akaza-reset;
@import "tailwindcss";
@import "akaza-ui/dist/akaza-ui.css";
With description
Use description when the switch label needs more context.
<template>
<Avatar
src="/avatar.jpg"
alt="Jane Doe"
text="JD"
:delay-ms="300"
/>
</template>
Custom true/false values
Use custom values when the model stores domain values instead of booleans.
<Button
:ui="{
root: 'rounded-md bg-black px-3 py-2 text-white',
spinner: 'size-4 animate-spin',
}"
>
Save
</Button>
Icon-only switch
Use aria-label when there's no visible label text.
<template>
<Button
as="a"
href="/docs"
>
Read the docs
</Button>
</template>
Field and native forms
Switch inherits Field metadata and registers focused, touched, dirty, filled, and invalid state. Required validation does not depend on providing a name. Invalid submission focuses the visible switch; untouched empty controls are not immediately marked invalid.
Label clicks respect native disabled fieldsets and ignore embedded links. Native reset restores the mount-time model unless canceled. class and ui.wrapper target the outer wrapper; ui.root targets the switch button. Supply visual spacing and disabled appearance in your ui classes.
API Reference
Props
| Prop | Type | Default | Description |
|---|---|---|---|
disabled | boolean | false | Disables the switch. |
id | string | auto | HTML id for the button element. |
name | string | — | HTML name for form submission. |
required | boolean | false | Marks the field as required. |
trueValue | boolean | string | number | true | Model value when switched on. |
falseValue | boolean | string | number | false | Model value when switched off. |
label | string | — | Label text. Slot #label takes priority. |
description | string | — | Description text. Slot #description takes priority. |
ariaLabel | string | — | aria-label for icon-only switches with no visible label. |
ui | SwitchUi | — | CSS class overrides. |
Slots
| Slot | Scoped props | Description |
|---|---|---|
thumb | { checked } | The sliding thumb indicator. |
label | — | Label text. Defaults to the label prop. |
description | — | Description text. Defaults to the description prop. |
Emits
| Event | Payload | Description |
|---|---|---|
value-change | [value: SwitchValue, details] | Fired when the switch state changes. |
UI Options
| Key | Description |
|---|---|
wrapper | The outer wrapper element. |
root | The interactive button (the switch track). |
thumb | The thumb indicator element. |
input | Hidden native input used for form submission. |
text | Wrapper around label and description. |
label | The label element. |
description | The description element. |
Styling Hooks
| UI key | CSS class | Data attrs |
|---|---|---|
wrapper | akaza-switch-wrapper | — |
root | akaza-switch | data-akaza-state, data-akaza-disabled, data-akaza-invalid, data-akaza-dirty, data-akaza-touched, data-akaza-focused, data-akaza-filled |
thumb | akaza-switch-thumb | data-akaza-state |
input | akaza-switch-input | — |
text | akaza-switch-text | — |
label | akaza-switch-label | — |
description | akaza-switch-description | — |
Keyboard
| Key | Behavior |
|---|---|
Enter / Space | Toggles focused switch. |
Tab / Shift + Tab | Uses native document focus order. |
Visible label is associated with switch, so mouse and touch activation on label also toggles it.