Switch
Change an on/off setting immediately, returning to the previous position if the app rejects the change.
<script setup lang="ts">import { ref } from 'vue'import { UiSwitch } from 'grani' const summary = ref(true) const mentions = ref(false) const longOne = ref(false)</script> <template> <div class="flex w-64 max-w-full flex-col items-start gap-4"> <UiSwitch v-model="summary">Weekly summary</UiSwitch> <UiSwitch v-model="mentions">Mentions</UiSwitch> <UiSwitch v-model="longOne"> Send me a summary of every comment, mention and status change on the projects I follow </UiSwitch> </div></template>
Also called toggle, toggle switch, on off switch.
Usage
<UiSwitch v-model="value">…</UiSwitch> With GraniResolver in the Vite config, a template needs no import: set it up once.
API
| Name · type | Default | Description |
|---|---|---|
| Value | ||
| modelValue*boolean | On or off (v-model). | |
| State | ||
| loadingboolean= false | false | The change is being saved: a spinner in the thumb, aria-busy, no toggling; focus stays. |
| Behavior | ||
| valuestring= "on" | "on" | Sent under name while on. |
| Look | ||
| sizesm | md= "sm" | "sm" | Track size: sm 20px, md 24px. |
| Form and access | ||
| disabledboolean= false | false | Prevents toggling. |
| namestring | Native name for forms: an on switch sends value under it, an off one nothing. | |
| ariaLabelstring | Accessible name when the slot is empty and there is no field label; slot text wins over it. | |
| idstring | Own id when standalone. Inside UiField the field's id takes precedence. | |
| invalidboolean= false | false | Marks the switch invalid: the track takes the danger tone while off. Inside UiField the error sets this. |
| requiredboolean= false | false | Standalone only: the switch must be on, said to a reader, with a star after its text. Inside UiField the field's required says so. |
Attributes: class and style stay on the outer element; the rest (native attributes, aria-*, data-testid) reach the control inside it.
When to use another component
| When you need | Take |
|---|---|
| Saved with the form, not applied at once | Checkbox |
| One answer out of a few | Radio group |
| A toggle that is a button | Button pressed |