Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Forms

Switch

A labelled on/off control built on a native checkbox.

Last changed in version 0.14.2: Improve keyboard navigation, action feedback, and selected colors across Vue components.

Interactive showcase

Install

Run in your project
bunx --bun @getweini/cli@latest add switch

Start with this example

Import the files copied by the install command, then place the component in your Vue template. The text and values in the example belong to your app; change them to fit your task.

Vue
<script setup lang="ts">
import { ref } from 'vue'
import Label from './components/ui/label/Label.vue'
import Switch from './components/ui/switch/Switch.vue'

const alerts = ref(true)
</script>

<template>
  <Switch id="alerts" v-model="alerts" />
  <Label for="alerts">Notifications</Label>
</template>

Space and label activation work natively. Checked switches submit their value; unchecked switches submit nothing. The thumb stretches slightly toward the new position while pressed, then settles into its round shape. This movement follows RTL direction and becomes immediate when reduced motion is enabled.

When to use it

Immediate preference

Turn account notifications on or off as a persistent setting.

Feature availability

Disable a preference that the current plan does not allow.

More examples

Email alerts

A stable label describes the setting in both states.

Email alerts
<script setup lang="ts">
import { ref } from 'vue'
import Label from './components/ui/label/Label.vue'
import Switch from './components/ui/switch/Switch.vue'

const alerts = ref(true)
</script>
<template>
  <Switch id="alerts" v-model="alerts" name="alerts" value="enabled" />
  <Label for="alerts">Email alerts</Label>
</template>

Unavailable setting

Disable both control and related explanatory presentation.

Unavailable setting
<script setup lang="ts">
import { ref } from 'vue'
import Label from './components/ui/label/Label.vue'
import Switch from './components/ui/switch/Switch.vue'

const audit = ref(false)
</script>
<template>
  <Switch id="audit" v-model="audit" disabled aria-describedby="audit-help" />
  <Label for="audit" disabled>Audit log</Label>
  <p id="audit-help">Available on the Team plan.</p>
</template>

Complete API

Every public prop, model, event, slot, and exposed member of the installed Vue parts is listed below. “Not set” means you can leave that value out; “Required” means you must provide it. Native HTML attributes also work where the component uses a native element.

Switch

Complete API for Switch
NameType or signatureDefaultWhat it does
sizepropControlSize | undefined"md"Choose the visual size. Medium is the usual default where available.
invalidpropboolean | undefinedNot setShow the invalid state; also provide a visible error message.
modelValuemodelboolean | undefinedfalseCurrent value. Use v-model to keep it in sync with your page.
update:modelValueevent[value: boolean]—Requests a new model value from the parent.
errorslot{ message: string; messages: string[]; }OptionalContent for the error area of Switch.
elementexposedHTMLInputElement | null—Reference to the underlying HTML element.
focusexposed() => void | undefined—Move keyboard focus to this control.
Public type definitions
Public types
// packages/frameworks/vue/components/switch/types.ts
// ------- IMPORTS -------

import type { ControlSize } from '@getweini/vue/types'

// ------- TYPES -------

export interface SwitchProps {
  size?: ControlSize
  invalid?: boolean
}


// packages/frameworks/vue/dist/types/index.d.ts
export type { ButtonOptions, ButtonProps } from './button';
export type ControlSize = 'sm' | 'md' | 'lg';
export interface SelectOption<T = unknown> {
    label: string;
    value: T;
    disabled?: boolean;
}
/** Application-owned copy. Bind translated strings reactively when the locale changes. */
export interface ListboxMessages {
    /** Popup name when no aria-label or aria-labelledby is supplied. */
    listboxLabel: string;
    empty: string;
    clearSelection: string;
}
export interface ListboxProps<T> {
    options: readonly SelectOption<T>[];
    messages: ListboxMessages;
    id?: string;
    disabled?: boolean;
    required?: boolean;
    invalid?: boolean;
    name?: string;
    form?: string;
    placeholder?: string;
    size?: ControlSize;
    clearable?: boolean;
    gap?: number;
    /** Supply stable equality for object values. Values must be unique. */
    by?: (a: T, b: T) => boolean;
    /** Required for meaningful form submission of object values. */
    serialize?: (value: T) => string;
}


// packages/frameworks/vue/dist/types/button.d.ts
import type { Component } from 'vue';
/** Options shared by button implementations across frameworks. */
export interface ButtonOptions<Variant extends string = string, Size extends string = string> {
    variant?: Variant;
    size?: Size;
    disabled?: boolean;
    loading?: boolean;
    type?: 'button' | 'submit' | 'reset';
}
/** Vue-specific target options extend the reusable button contract. */
export interface ButtonProps<Variant extends string = 'default' | 'secondary' | 'outline' | 'ghost' | 'destructive', Size extends string = 'sm' | 'md' | 'lg'> extends ButtonOptions<Variant, Size> {
    as?: 'button' | 'a' | Component;
    asChild?: boolean;
}

Implementation notes

  • A checked named switch submits its value; an unchecked switch submits nothing.
  • Use a switch for an on/off setting, especially one that takes effect immediately.

Accessibility and localization

  • Keep label wording stable when state changes. The native checkbox supplies Space and focus behavior with switch semantics.

Source contract and editing guidance