Forms

InputMask

Campo di testo con maschera di formattazione per input strutturati come date, codici fiscali, numeri di telefono e codici seriali. Supporta pattern con caratteri speciali e opzioni di autoclear.

Import

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

Esempio Base

Sintassi della Maschera

Carattere	Corrisponde a
`9`	Cifra numerica (0-9)
`a`	Carattere alfabetico (a-z, A-Z)
`*`	Carattere alfanumerico (a-z, A-Z, 0-9)
`?`	Rende opzionale tutto ciò che segue
`\`	Escape: il carattere successivo è letterale

Props

Prop	Tipo	Default	Descrizione
`modelValue`	`string \| null`	—	Valore del campo (v-model)
`defaultValue`	`string \| null`	—	Valore predefinito (modalità non controllata)
`mask`	`string`	—	Pattern della maschera (es: `'99/99/9999'`, `'(999) 999-9999'`)
`slotChar`	`string`	`'_'`	Carattere placeholder mostrato nelle posizioni non compilate
`autoClear`	`boolean`	`true`	Cancella il valore se la maschera non è completamente compilata al blur
`unmask`	`boolean`	`false`	Se `true`, emette il valore senza i caratteri letterali della maschera
`label`	`string`	—	Label mostrata sopra il campo
`placeholder`	`string`	—	Testo placeholder (default: il pattern della maschera)
`helperText`	`string`	—	Testo di aiuto sotto il campo
`error`	`string`	—	Messaggio di errore (sovrascrive helperText)
`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: un `error` resta comunque visibile (dalla 1.23.0)
`variant`	`'outlined' \| 'filled'`	`'outlined'`	Variante visiva del campo. Il bordo di `outlined` usa `--color-field-border`, almeno 3:1 su ogni superficie (dalla 1.24.0)
`size`	`'small' \| 'medium' \| 'large'`	`'medium'`	Dimensione del campo
`disabled`	`boolean`	`false`	Disabilita il campo
`readonly`	`boolean`	`false`	Campo in sola lettura
`required`	`boolean`	`false`	Campo obbligatorio
`invalid`	`boolean`	`false`	Stato di validazione invalido
`fluid`	`boolean`	`false`	Occupa tutta la larghezza disponibile
`loading`	`boolean`	`false`	Mostra indicatore di caricamento
`loadingIcon`	`string`	config globale	Classe CSS icona di caricamento
`autocomplete`	`string`	—	Valore attributo autocomplete HTML
`id`	`string`	auto-generato	ID dell'elemento input
`name`	`string`	—	Nome del campo per form nativi
`tabindex`	`number`	—	Ordine di tabulazione
`ariaLabel`	`string`	—	Label ARIA per screen reader
`ariaLabelledby`	`string`	—	ID elemento che funge da label ARIA
`ariaDescribedby`	`string`	—	ID elemento con descrizione aggiuntiva
`maskDescription`	`string`	—	Descrizione del formato per screen reader (es: `"Formato: GG/MM/AAAA"`)
`inputClass`	`string \| null`	—	Classe CSS aggiuntiva per l'input
`inputStyle`	`string \| object \| null`	—	Stile inline per l'input
`autofocus`	`boolean`	`false`	Focus automatico al mount

Emits

Evento	Payload	Descrizione
`update:modelValue`	`string`	Aggiornamento v-model
`valueChange`	`string`	Cambio valore (modalità non controllata)
`complete`	`{ originalEvent: Event, value: string }`	Emesso quando la maschera è completamente compilata
`focus`	`FocusEvent`	Quando il campo riceve il focus
`blur`	`FocusEvent`	Quando il campo perde il focus
`keydown`	`KeyboardEvent`	Alla pressione di un tasto
`paste`	`ClipboardEvent`	Al paste di contenuto (la maschera viene applicata automaticamente)

Esempi

Maschere comuni

Con unmask (valore senza maschera)

Con maschera opzionale

Con accessibilità avanzata

Accessibilità

La prop maskDescription aggiunge un testo nascosto visivamente (sr-only) collegato all'input tramite aria-describedby
aria-invalid viene impostato automaticamente quando invalid o error sono presenti
aria-required e aria-busy sono gestiti automaticamente
Il cursore viene posizionato automaticamente alla prima posizione libera al focus
I tasti ArrowLeft/ArrowRight navigano tra le posizioni della maschera
Al paste, la maschera viene applicata automaticamente filtrando i caratteri validi

TypeScript

import type { InputMaskProps } from '@pzeta/vue-components'

const maskProps: InputMaskProps = {
  mask: '99/99/9999',
  label: 'Data',
  slotChar: '_',
  autoClear: true,
  unmask: false,
  maskDescription: 'Formato: GG/MM/AAAA',
}

InputGroup

Wrapper per raggruppare un input con addon testuali o iconografici (prefix/suffix). Deve essere usato insieme a InputGroupAddon per aggiungere decoratori prima o dopo l'input.

InputNumber

Campo numerico con formattazione locale, supporto valute, pulsanti stepper e gestione min/max/step. Usa Intl.NumberFormat per la formattazione.