Forms

MultiSelect

Dropdown per la selezione multipla con chips, filtro, toggle-all e limite di selezione. Supporta visualizzazione comma e chip per i valori selezionati.

Import

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

Esempio Base

Props

Prop	Tipo	Default	Descrizione
`modelValue`	`OptionValue[]`	`[]`	Array di valori selezionati (v-model)
`options`	`Array<string \| number \| Record<string, unknown>>`	`[]`	Array di opzioni
`optionLabel`	`string \| ((o) => string)`	`null`	Proprietà o funzione per il testo visualizzato
`optionValue`	`string \| ((o) => OptionValue)`	`null`	Proprietà o funzione per il valore
`optionDisabled`	`string \| ((o) => boolean)`	`null`	Proprietà o funzione per opzione disabilitata
`optionGroupLabel`	`string \| ((o) => string)`	`null`	Label del gruppo di opzioni
`optionGroupChildren`	`string \| ((o) => Record<string,unknown>[])`	`null`	Proprietà con le opzioni figlie
`placeholder`	`string`	—	Testo quando nessuna opzione è selezionata
`display`	`'comma' \| 'chip'`	`'comma'`	Modalità di visualizzazione dei valori selezionati
`maxSelectedLabels`	`number`	`3`	Numero massimo di label prima di mostrare il conteggio
`selectedItemsLabel`	`string`	—	Testo mostrato quando le selezioni superano `maxSelectedLabels`
`selectionLimit`	`number`	`null`	Numero massimo di selezioni consentite
`showToggleAll`	`boolean`	`true`	Mostra checkbox per selezionare/deselezionare tutto
`filter`	`boolean`	`false`	Mostra campo di ricerca nel dropdown
`filterMatchMode`	`'startsWith' \| 'contains' \| 'endsWith'`	`'contains'`	Modalità di matching del filtro
`filterPlaceholder`	`string`	—	Placeholder del campo filtro
`filterFields`	`string[]`	`null`	Campi su cui applicare il filtro
`showClear`	`boolean`	`false`	Mostra pulsante per azzerare tutte le selezioni
`label`	`string`	`null`	Label mostrata sopra il campo
`helperText`	`string`	`null`	Testo di aiuto sotto il campo
`error`	`string`	`null`	Messaggio di errore
`reserveMessageSpace`	`boolean`	`true`	Riserva lo spazio del messaggio sotto il campo; `false` nelle barre filtri (dalla 1.19.0)
`invalid`	`boolean`	`false`	Stato di validazione invalido
`disabled`	`boolean`	`false`	Disabilita il componente. Lo stile (bordo, sfondo, testo) è lo stesso di `InputText`, con l'opacità solo sul wrapper (dalla 1.24.0)
`readonly`	`boolean`	`false`	Campo in sola lettura
`required`	`boolean`	`false`	Campo obbligatorio
`fluid`	`boolean`	`true`	Occupa tutta la larghezza disponibile
`size`	`'small' \| 'medium' \| 'large'`	`'medium'`	Dimensione del componente
`variant`	`'outlined' \| 'filled'`	`'outlined'`	Variante visiva
`severity`	`Severity`	`'primary'`	Colore tema
`loading`	`boolean`	`false`	Stato di caricamento
`scrollHeight`	`string`	`'14rem'`	Altezza massima del dropdown
`appendTo`	`'body' \| 'self'`	`'body'`	Target Teleport del dropdown
`dataKey`	`string`	`null`	Chiave univoca per le opzioni
`inputId`	`string`	`null`	ID dell'input per accessibilità
`name`	`string`	`null`	Nome per i form nativi
`ariaLabel`	`string`	`null`	Aria label per screen reader
`ariaLabelledby`	`string`	`null`	ID dell'elemento label ARIA
`checkmark`	`boolean`	`true`	Mostra checkbox accanto a ogni opzione
`highlightOnSelect`	`boolean`	`true`	Evidenzia le opzioni selezionate
`autoFilterFocus`	`boolean`	`false`	Focus automatico sul filtro all'apertura
`resetFilterOnHide`	`boolean`	`true`	Resetta il filtro alla chiusura del dropdown
`resetFilterOnClear`	`boolean`	`true`	Resetta il filtro al clear
`defaultValue`	`OptionValue[]`	`null`	Valore predefinito se modelValue non è fornito
`loadingIcon`	`string`	—	Classe CSS icona di caricamento
`clearIcon`	`string`	—	Classe CSS icona di cancellazione
`dropdownIcon`	`string`	—	Classe CSS icona dropdown

Emits

Evento	Payload	Descrizione
`update:modelValue`	`OptionValue[]`	Aggiornamento v-model
`change`	`{ originalEvent: Event, value: OptionValue[] }`	Cambio di selezione
`filter`	`{ originalEvent: Event, value: string }`	Cambio del testo filtro
`clear`	`Event`	Tutte le selezioni azzerate
`selectAllChange`	`{ originalEvent: Event, checked: boolean }`	Toggle-all attivato
`chipRemove`	`{ originalEvent: Event, value: OptionValue }`	Chip rimossa
`focus`	`Event`	Il componente riceve il focus
`blur`	`Event`	Il componente perde il focus
`keydown`	`KeyboardEvent`	Pressione tasto
`keyup`	`KeyboardEvent`	Rilascio tasto
`beforeShow`	—	Prima dell'apertura del dropdown
`show`	—	Dropdown aperto
`beforeHide`	—	Prima della chiusura del dropdown
`hide`	—	Dropdown chiuso

Slot

Slot	Scope	Descrizione
`value`	`{ value: OptionValue[], placeholder: string \| null }`	Personalizza la visualizzazione del valore in modalità comma
`chip`	`{ value: OptionValue, option: Record<string, unknown> }`	Template per ogni chip in modalità chip
`option`	`{ option, selected, index }`	Template per ogni singola opzione
`optiongroup`	`{ option }`	Template per l'intestazione del gruppo
`header`	—	Contenuto in cima al dropdown
`footer`	—	Contenuto in fondo al dropdown
`content`	`{ options, value, selectOption }`	Override completo del contenuto del dropdown
`empty`	—	Messaggio quando non ci sono opzioni
`emptyfilter`	—	Messaggio quando il filtro non produce risultati
`loader`	—	Stato di caricamento nel dropdown
`loadingicon`	—	Icona di caricamento personalizzata
`clearicon`	—	Icona del pulsante clear personalizzata
`dropdownicon`	`{ expanded: boolean }`	Icona del dropdown personalizzata
`removetokenicon`	—	Icona di rimozione chip personalizzata
`headercheckboxicon`	`{ allSelected, partialSelected }`	Icona checkbox del toggle-all
`itemcheckboxicon`	`{ selected: boolean }`	Icona checkbox di ogni opzione

Esempi

Modalità chip

I valori selezionati vengono visualizzati come badge rimuovibili nel trigger:

Limite di selezione

Con filtro di ricerca

Numero massimo di label

Quando le selezioni superano maxSelectedLabels, viene mostrato un conteggio:

Stati

Chip personalizzata

Accessibilità

Il trigger ha role="combobox" con aria-expanded e aria-haspopup="listbox"
Supporto navigazione tastiera: ArrowDown/Up naviga le opzioni, Enter/Space seleziona/deseleziona, Escape chiude
Un clic su un'opzione o su «seleziona tutti» non toglie il focus al campo (o al filtro), come nel pattern combobox: la tendina resta aperta e il tasto successivo arriva ancora a lei (dalla 1.24.0)
In un Dialog, Escape chiude solo la tendina e il dialog si chiude al tasto successivo; vale anche se il focus è finito sul body (useEscapeWhileOpen, dalla 1.24.0)
Il pulsante di rimozione di ogni chip si chiama «Rimuovi » (dalla 1.24.0)
Il toggle-all è cliccabile e supporta stato parziale (partial check)
aria-label e aria-labelledby configurabili

TypeScript

import type { MultiSelectProps, MultiSelectEmits } from '@pzeta/vue-components'

const selectedCodes = ref<string[]>([])

const cities: Array<{ name: string; code: string }> = [
  { name: 'Roma', code: 'RM' },
  { name: 'Milano', code: 'MI' },
]

Listbox

Lista di selezione sempre visibile (non dropdown) con supporto a selezione singola e multipla, filtro, opzioni raggruppate e checkmark. Ideale per pannelli e form con spazio dedicato.

Password

Campo password con toggle visibilità, clear button e contatore caratteri. Supporta la stessa API di InputText con l'aggiunta del pulsante show/hide password.