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'

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)

<template>
  <Checkbox
    v-model="selectAll"
    label="Seleziona tutto"
    :indeterminate="isIndeterminate"
    binary
    @change="handleSelectAll"
  />
  <div class="ml-6 space-y-2">
    <Checkbox v-model="items" value="item1" label="Item 1" />
    <Checkbox v-model="items" value="item2" label="Item 2" />
    <Checkbox v-model="items" value="item3" label="Item 3" />
  </div>
</template>

<script setup lang="ts">
import { ref, computed, watch } from 'vue'

const selectAll = ref(false)
const items = ref<string[]>(['item1'])

const isIndeterminate = computed(() => items.value.length > 0 && items.value.length < 3)

watch(items, newValue => {
  selectAll.value = newValue.length === 3
})

const handleSelectAll = (event: { checked: boolean }) => {
  items.value = event.checked ? ['item1', 'item2', 'item3'] : []
}
</script>

Varianti

Con Helper Text ed Errore

Icona Personalizzata tramite Slot

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.