Forms

Checkbox

Casella di spunta con supporto per modalità binaria, selezione multipla tramite array, stato indeterminato e loading.

Import

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

Modalità d'uso

Il Checkbox supporta due modalità di binding selezionate automaticamente in base al tipo del modelValue:

Modalità	`modelValue`	`value`	Quando usarla
Binary	`boolean`	non usato	Singolo flag (accetta termini, opt-in, on/off senza animazione — vedi `ToggleSwitch` come alternativa)
Array	`unknown[]`	richiesto	Selezione multipla in un gruppo: il `value` viene aggiunto/rimosso dall'array

Aggiungi binary esplicitamente quando il modelValue iniziale è false/null/undefined: senza binary, il componente potrebbe interpretarlo come array vuoto.

Esempio Base

Props

Prop	Tipo	Default	Descrizione
`modelValue`	`boolean \| unknown[] \| null`	`false`	Valore del checkbox (v-model). Boolean in modalità binaria, array in modalità gruppo.
`value`	`unknown`	`undefined`	Valore associato al checkbox in modalità array; viene aggiunto/rimosso dall'array.
`binary`	`boolean`	`false`	Abilita la modalità binaria (true/false) invece di array.
`indeterminate`	`boolean`	`false`	Stato intermedio, né selezionato né deselezionato. Utile per "seleziona tutto" con selezione parziale.
`indeterminateIcon`	`string`	`'pi pi-minus'` (da config)	Icona CSS per lo stato indeterminato.
`checkIcon`	`string`	`'pi pi-check'` (da config)	Icona CSS di spunta.
`trueValue`	`boolean`	`true`	Valore emesso quando selezionato (modalità binaria custom).
`falseValue`	`boolean`	`false`	Valore emesso quando deselezionato (modalità binaria custom).
`defaultValue`	`boolean \| unknown[] \| null`	`null`	Valore predefinito se modelValue non è fornito.
`label`	`string`	`undefined`	Etichetta del checkbox.
`helperText`	`string`	`undefined`	Testo di aiuto visualizzato sotto il label.
`error`	`string`	`undefined`	Messaggio di errore; attiva lo stato di errore visivo.
`size`	`'small' \| 'medium' \| 'large'`	`'medium'`	Dimensione del checkbox.
`severity`	`'primary' \| 'secondary' \| 'success' \| 'info' \| 'warn' \| 'danger' \| 'help' \| 'contrast'`	`'primary'`	Colore/severità visiva.
`variant`	`'default' \| 'outlined' \| 'filled'`	`'default'`	Variante stilistica del checkbox.
`disabled`	`boolean`	`false`	Disabilita il componente.
`readonly`	`boolean`	`false`	Rende il componente non modificabile.
`loading`	`boolean`	`false`	Mostra il loading spinner al posto dell'icona di spunta.
`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`	`null`	Indice tab per navigazione da tastiera.
`autofocus`	`boolean`	—	Focus automatico al mount.

Emits

Evento	Payload	Descrizione
`update:modelValue`	`boolean \| unknown[]`	Emesso al cambio valore (per v-model).
`update:indeterminate`	`boolean`	Emesso al cambio dello stato indeterminato.
`change`	`{ originalEvent: Event; value: boolean \| unknown[]; checked: boolean }`	Emesso al cambio con dettagli completi sull'evento.
`focus`	`FocusEvent`	Emesso quando il componente riceve il focus.
`blur`	`FocusEvent`	Emesso quando il componente perde il focus.

Slot

Slot	Scope	Descrizione
`default`	—	Contenuto alternativo al prop `label`.
`icon`	`{ checked: boolean; indeterminate: boolean; class: string[] }`	Icona di spunta personalizzata.

Esempi

Gruppo con Array

Stato Indeterminato (Seleziona Tutto)

Varianti

Con Helper Text ed Errore

Stato Loading

Durante il loading lo spinner sostituisce l'icona di spunta. Combinabile con disabled per bloccare l'interazione.

Valori personalizzati (trueValue/falseValue)

Utile quando il backend si aspetta valori diversi da true/false (es. 'Y'/'N', 1/0).

Icona Personalizzata tramite Slot

Metodi Esposti

Metodo	Descrizione
`focus()`	Porta il focus sull'input nascosto

<script setup>
import { ref } from 'vue'
const checkboxRef = ref(null)
function focusFirst() {
  checkboxRef.value?.focus()
}
</script>
<template>
  <Checkbox ref="checkboxRef" label="Esempio" binary />
</template>

Accessibilità

L'input <input type="checkbox"> è nascosto visivamente (sr-only) ma rimane accessibile agli screen reader.
inputId associa il checkbox a un elemento <label> esterno.
ariaLabel e ariaLabelledby forniscono descrizioni accessibili aggiuntive.
Quando required è true, viene aggiunta * visivamente e un testo (obbligatorio) per screen reader.
La navigazione da tastiera è supportata tramite tabindex e il comportamento nativo del checkbox.

TypeScript

import type { CheckboxProps, CheckboxEmits } from '@pzeta/vue-components'

Calendar

Calendario inline standalone per la selezione di date in modalita singola, multipla o intervallo. Non include input testuale — usare DatePicker per il pattern input+popup.

Clock

Picker orario standalone con interfaccia orologio analogico SVG o variante compatta a frecce. Supporta modalita durata, intervalli e precisione minuti personalizzabile.