Forms

DatePicker

Input data con calendario popup e auto-completamento intelligente. Supporta selezione singola, multipla e a intervallo, opzioni rapide e bottoni di conferma.

Import

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

Formato Valore

Direzione	Formato
`modelValue` in ingresso	`YYYY-MM-DD` (single), `Date[]` (multiple/range) o `null`
`update:modelValue` in uscita	`YYYY-MM-DD` (single), `Date[]` (multiple/range) o `null`
Visualizzato all'utente	`DD/MM/YYYY` (locale `it`)

Auto-completamento intelligente — In modalità singola l'utente può digitare solo il giorno (completato con mese/anno correnti) o giorno+mese (completato con anno corrente). Es. digitando 5 in dicembre 2025 si ottiene 05/12/2025.

Props

Prop	Tipo	Default	Descrizione
`modelValue`	`string \| Date \| Date[] \| null`	—	Valore corrente (v-model)
`defaultValue`	`string \| Date \| Date[] \| null`	—	Valore iniziale non controllato
`label`	`string`	—	Label del campo
`placeholder`	`string`	locale	Testo placeholder (default da i18n)
`helperText`	`string`	—	Testo di aiuto sotto il campo
`error`	`string`	—	Messaggio di errore
`reserveMessageSpace`	`boolean`	`true`	Riserva sotto il campo lo spazio del messaggio anche senza `helperText` né `error`, così un errore non sposta i campi sotto. `false` nelle barre filtri (dalla 1.19.0)
`disabled`	`boolean`	`false`	Disabilita il componente
`readonly`	`boolean`	`false`	Sola lettura
`loading`	`boolean`	`false`	Mostra spinner di caricamento
`required`	`boolean`	`false`	Campo obbligatorio
`invalid`	`boolean`	`false`	Forza stato errore
`size`	`'small' \| 'medium' \| 'large'`	`'medium'`	Dimensione dell'input
`severity`	`Severity`	`'primary'`	Colore del tema
`variant`	`'outlined' \| 'filled'`	`'outlined'`	Variante visiva
`fluid`	`boolean`	`false`	Adatta la larghezza al contenitore
`rounded`	`boolean`	`false`	Bordi arrotondati
`showClear`	`boolean`	`false`	Mostra pulsante di svuotamento
`showIcon`	`boolean`	`true`	Mostra icona calendario
`iconDisplay`	`'button' \| 'input'`	`'button'`	Posizione icona: suffix button o prefix input
`manualInput`	`boolean`	`true`	Permette la digitazione manuale
`inline`	`boolean`	`false`	Calendario sempre visibile senza popup
`min`	`string`	—	Data minima in formato `YYYY-MM-DD`
`max`	`string`	—	Data massima in formato `YYYY-MM-DD`
`minDate`	`Date \| null`	—	Data minima come oggetto Date
`maxDate`	`Date \| null`	—	Data massima come oggetto Date
`disabledDates`	`Date[] \| null`	—	Lista di date disabilitate
`disabledDays`	`number[] \| null`	—	Giorni della settimana disabilitati (0=Dom, 6=Sab)
`selectionMode`	`'single' \| 'multiple' \| 'range'`	`'single'`	Modalità di selezione
`dateFormat`	`string`	—	Formato di visualizzazione data
`showTime`	`boolean`	—	Mostra selettore orario nel calendario
`timeOnly`	`boolean`	—	Solo selettore orario
`hourFormat`	`'12' \| '24'`	—	Formato ore
`numberOfMonths`	`number`	—	Numero di mesi visualizzati affiancati
`showWeek`	`boolean`	—	Mostra numero settimana
`showWeekNumbers`	`boolean`	`false`	Mostra numeri di settimana nella colonna sinistra
`showButtonBar`	`boolean`	—	Mostra barra pulsanti oggi/clear nel calendario
`showQuickOptions`	`boolean`	`false`	Mostra opzioni rapide (Oggi, Domani, ecc.)
`quickOptions`	`CalendarQuickOption[]`	—	Opzioni rapide personalizzate
`firstDayOfWeek`	`number`	locale	Primo giorno settimana (0=Dom, 1=Lun)
`showActionButtons`	`boolean`	`false`	Chiude popup solo su conferma/annulla
`view`	`'date' \| 'month' \| 'year'`	—	Vista iniziale del calendario
`yearRange`	`string \| null`	—	Intervallo anni selezionabili (es. `'1900:2030'`)
`touchUI`	`boolean`	—	Ottimizzato per dispositivi touch
`prefixIcon`	`string`	—	Classe icona prefix
`suffixIcon`	`string`	—	Classe icona suffix
`clearIcon`	`string`	config	Classe icona clear (override config)
`loadingIcon`	`string`	config	Classe icona loading (override config)
`inputId`	`string`	auto	ID dell'elemento input
`inputClass`	`string \| null`	—	Classe CSS aggiuntiva per l'input
`inputStyle`	`string \| Record<string, string \| number> \| null`	—	Stile inline per l'input
`name`	`string`	—	Nome del campo per form submission
`autofocus`	`boolean`	`false`	Focus automatico al mount

Emits

Evento	Payload	Descrizione
`update:modelValue`	`string \| Date \| Date[] \| null`	Aggiornamento valore (v-model)
`input`	`{ originalEvent: Event; value: string \| Date \| Date[] \| null }`	Input testuale
`change`	`{ originalEvent: Event; value: string \| Date \| Date[] \| null }`	Cambio valore confermato
`focus`	`FocusEvent`	Focus sull'input
`blur`	`FocusEvent`	Blur dall'input
`keydown`	`KeyboardEvent`	Tasto premuto
`keyup`	`KeyboardEvent`	Tasto rilasciato
`keypress`	`KeyboardEvent`	Tasto premuto (keypress)
`clear`	`MouseEvent`	Click sul pulsante clear
`dateSelect`	`Date \| Date[]`	Data selezionata nel calendario
`todayClick`	—	Click su "Oggi" nel calendario
`clearClick`	—	Click su "Clear" nel calendario
`monthChange`	`{ month: number; year: number }`	Cambio mese nella navigazione
`yearChange`	`{ month: number; year: number }`	Cambio anno nella navigazione
`beforeShow`	—	Prima dell'apertura popup
`show`	—	Popup aperto
`beforeHide`	—	Prima della chiusura popup
`hide`	—	Popup chiuso
`confirm`	`string \| Date \| Date[] \| null`	Conferma selezione (con `showActionButtons`)
`cancel`	—	Annullamento selezione (con `showActionButtons`)

Slot

Slot	Descrizione
`icon`	Sostituzione dell'icona calendario
`calendar-header`	Contenuto aggiuntivo nell'header del popup calendario
`calendar-footer`	Contenuto aggiuntivo nel footer del popup calendario

Esempi

Con limiti di data

Una data digitata fuori da min/max (o minDate/maxDate) non viene accettata: all'uscita dal campo il valore torna all'ultimo valido e sotto compare il motivo, per esempio «La data non può essere precedente al 01/01/1900», annunciato agli screen reader (role="alert", aria-invalid, aria-describedby). Prima veniva scartata in silenzio. Il messaggio sparisce quando si riscrive o si sceglie una data dal calendario; un error passato dal chiamante ha la precedenza (dalla 1.24.0).

Con opzioni rapide e conferma

Con show-action-buttons il popup si chiude solo premendo OK o Annulla. Il valore viene aggiornato solo alla conferma e l'evento confirm riceve il valore finale in formato ISO.

Selezione multipla

In modalità multiple il modelValue è un Date[]. Ogni click sul calendario aggiunge/rimuove la data dall'array.

Selezione range

In modalità range il primo click seleziona la data di inizio, il secondo la data di fine. Usa number-of-months per visualizzare più mesi affiancati e facilitare la selezione.

Calendario inline

Con giorni disabilitati

disabledDays accetta un array di indici (0=Domenica, 6=Sabato). Per disabilitare date specifiche usa disabledDates: Date[].

Opzioni rapide personalizzate

Metodi Esposti

Metodo	Descrizione
`focus()`	Porta il focus sull'input
`blur()`	Rimuove il focus dall'input
`select()`	Seleziona il testo nell'input
`open()`	Apre il calendario popup
`close()`	Chiude il calendario popup
`toggle()`	Alterna apertura/chiusura del popup

Accessibilità

Input associato alla label tramite id generato automaticamente o inputId
L'icona calendario è un <button> con tabindex="-1" (fuori dal tab order)
All'apertura il focus entra nella griglia, sul giorno selezionato o su oggi (dalla 1.24.0)
Tab e Maiusc+Tab restano dentro il popup anche in un Dialog: il popup è teleportato fuori dal dialog, e prima il focus trap del Dialog riportava il focus nel dialog (dalla 1.24.0)
Il popup si chiude con Escape, e in un Dialog chiude solo il popup: il dialog si chiude al tasto successivo. Vale anche col focus sul body (per esempio dopo il pulsante che apre il calendario), grazie a useEscapeWhileOpen (dalla 1.24.0)
Si apre con Enter quando l'input ha il focus
ariaLabel e ariaLabelledby per descrizioni accessibili aggiuntive

Per selezionare data e ora insieme usa il componente dedicato DateTimePicker invece di DatePicker con showTime.

TypeScript

import type { DatePickerProps, DatePickerEmits, CalendarQuickOption } from '@pzeta/vue-components'

// Valore in formato ISO YYYY-MM-DD
const dateValue = ref<string>('')

// Opzioni rapide tipizzate
const quickOptions: CalendarQuickOption[] = [
  { label: 'Oggi', value: () => new Date() },
]

ColorPicker

Selettore colore nativo con formato hex, visualizzazione del valore, label, stati di errore e loading.

DateTimePicker

Input combinato data e ora con popup che integra un Calendar e un Clock compatto. Il valore e sempre in formato ISO 8601 YYYY-MM-DDTHH:MM.