Forms

ToggleSwitch

Interruttore on/off con icone personalizzabili, supporto per trueValue/falseValue, varianti di dimensione e severità.

Import

import { ToggleSwitch } from '@pzeta/vue-components'

Quando usare ToggleSwitch vs Checkbox

Scenario	Componente
Attivare/disattivare un'impostazione con effetto immediato (notifiche, dark mode, sync)	`ToggleSwitch`
Confermare condizioni prima del submit (accetta termini, opt-in newsletter)	`Checkbox` con `binary`
Selezione multipla in un gruppo	`Checkbox` array mode
Stato indeterminato ("seleziona tutto" parziale)	`Checkbox` con `indeterminate`

ToggleSwitch è solo binario — non supporta array, value, né stato indeterminato. Per quei casi vai su Checkbox.

Esempio Base

Props

Prop	Tipo	Default	Descrizione
`modelValue`	`boolean \| null`	`false`	Valore dello switch (v-model).
`defaultValue`	`boolean \| null`	—	Valore predefinito se modelValue non è fornito.
`trueValue`	`boolean`	`true`	Valore emesso quando lo switch è acceso.
`falseValue`	`boolean`	`false`	Valore emesso quando lo switch è spento.
`showIcons`	`boolean`	`false`	Mostra le icone on/off all'interno dell'handle dello switch.
`onIcon`	`string`	Da config (`toggleOn`)	Icona CSS visualizzata quando lo switch è acceso (richiede `showIcons`).
`offIcon`	`string`	Da config (`toggleOff`)	Icona CSS visualizzata quando lo switch è spento (richiede `showIcons`).
`label`	`string`	`null`	Etichetta visualizzata sopra lo switch.
`helperText`	`string`	`null`	Testo di aiuto visualizzato accanto allo switch.
`error`	`string`	`null`	Messaggio di errore; attiva lo stato di errore visivo.
`size`	`'small' \| 'medium' \| 'large'`	`'medium'`	Dimensione dello switch.
`severity`	`'primary' \| 'secondary' \| 'success' \| 'info' \| 'warn' \| 'danger' \| 'help' \| 'contrast'`	`'primary'`	Colore/severità visiva quando lo switch è acceso.
`variant`	`'default' \| 'outlined' \| 'filled'`	`'default'`	Variante stilistica dello switch.
`disabled`	`boolean`	`false`	Disabilita il componente.
`loading`	`boolean`	`false`	Mostra il loading spinner all'interno dell'handle.
`loadingIcon`	`string`	Da config	Icona personalizzata per il loading.
`required`	`boolean`	`false`	Marca il campo come obbligatorio.
`name`	`string`	`null`	Attributo name del campo (per form HTML).
`inputId`	`string`	`null`	ID dell'input nascosto (per associazione a label).
`inputClass`	`string \| object`	—	Classe CSS aggiuntiva sull'input.
`inputStyle`	`string \| object`	—	Style inline sull'input.
`ariaLabel`	`string`	—	Label accessibile per screen reader.
`ariaLabelledby`	`string`	—	Riferimento a elemento label esterno.
`tabindex`	`number`	—	Indice tab per navigazione da tastiera.
`autofocus`	`boolean`	—	Focus automatico al mount.

Emits

Evento	Payload	Descrizione
`update:modelValue`	`boolean`	Emesso al cambio valore (per v-model).
`change`	`{ originalEvent: Event; value: boolean }`	Emesso al cambio con l'evento originale e il nuovo valore.
`focus`	`FocusEvent`	Emesso quando il componente riceve il focus.
`blur`	`FocusEvent`	Emesso quando il componente perde il focus.
`keydown`	`KeyboardEvent`	Emesso ad ogni pressione di tasto (Spazio/Enter attivano il toggle).

Slot

Slot	Scope	Descrizione
`default`	—	Contenuto del label. Sovrascrive il prop `label` se entrambi presenti.
`handle`	`{ checked: boolean }`	Contenuto personalizzato all'interno dell'handle dello switch. Sostituisce loading spinner e icone.

Esempi

Con Icone

Con Helper Text

Severità

Dimensioni

Handle Personalizzato tramite Slot

Valori personalizzati (trueValue/falseValue)

Utile per contratti API che usano enumerati invece di booleani.

Stato Disabilitato e Loading

Metodi Esposti

Metodo	Descrizione
`focus()`	Porta il focus sullo switch (button)

Accessibilità

Lo switch è implementato come <button type="button"> con navigazione da tastiera nativa.
Spazio e Invio attivano il toggle da tastiera.
L'input <input type="checkbox"> nascosto (sr-only) garantisce compatibilità con form HTML e screen reader.
inputId associa l'input a una label esterna.
Il prop required aggiunge * visivo per l'utente.

TypeScript

import type { ToggleSwitchProps, ToggleSwitchEmits } from '@pzeta/vue-components'

TimePicker

Input orario con popup Clock picker analogico o compatto. Supporta formato 24h, step personalizzabili e modalita durata.

TreeSelect

Dropdown con struttura ad albero per selezione gerarchica. Supporta modalità single, multiple e checkbox con selezione a cascata, filtro e visualizzazione chip.