Forms

Select

Dropdown di selezione singola o multipla con supporto a filtro, opzioni raggruppate e chips. Componente custom con navigazione tastiera e type-ahead integrati.

Import

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

Quando usarlo

Scenario	Componente consigliato
Selezione singola da elenco chiuso (≤ ~50 opzioni), eventualmente con filtro	`Select`
Selezione multipla da elenco chiuso con chips	`Select` con `multiple` o `MultiSelect`
Selezione con ricerca asincrona o suggerimenti progressivi	`AutoComplete`
Lista lunga sempre visibile (no popup)	`Listbox`
Scelta visuale con icone/immagini	`SelectableCard`

Esempio Base

Opzioni: oggetti vs stringhe

Array di oggetti (caso tipico)

Specificare option-label e option-value per indicare quali proprietà usare come etichetta e valore:

Il v-model conterrà il valore della proprietà option-value (id nell'esempio sopra), non l'intero oggetto.

Array di stringhe

Se le opzioni sono stringhe primitive, omettere option-label e option-value:

Funzione come `optionLabel`

Props

Prop	Tipo	Default	Descrizione
`modelValue`	`OptionValue \| OptionValue[]`	`null`	Valore selezionato (v-model)
`options`	`T[]`	`[]`	Array di opzioni
`optionLabel`	`string \| ((o: T) => string)`	`null`	Proprietà o funzione per il testo visualizzato
`optionValue`	`string \| ((o: T) => OptionValue)`	`null`	Proprietà o funzione per il valore
`optionDisabled`	`string \| ((o: T) => boolean)`	`null`	Proprietà o funzione per opzione disabilitata
`optionGroupLabel`	`string \| ((o: T) => string)`	`null`	Label del gruppo di opzioni
`optionGroupChildren`	`string \| ((o: T) => unknown[])`	`null`	Proprietà con le opzioni figlie di un gruppo
`placeholder`	`string`	locale	Testo quando nessuna opzione è selezionata (default da i18n `form.selectPlaceholder`)
`hidePlaceholderWhenSelected`	`boolean`	`true`	Nasconde il placeholder quando un'opzione è selezionata
`label`	`string`	`null`	Label mostrata sopra il campo
`helperText`	`string`	`null`	Testo di aiuto sotto il campo
`error`	`string`	`null`	Messaggio di errore
`invalid`	`boolean`	`false`	Stato di validazione invalido
`disabled`	`boolean`	`false`	Disabilita il componente
`readonly`	`boolean`	`false`	Campo in sola lettura
`required`	`boolean`	`false`	Campo obbligatorio
`multiple`	`boolean`	`false`	Abilita selezione multipla con chips
`filter`	`boolean`	`false`	Mostra campo di ricerca nel dropdown
`filterMatchMode`	`'startsWith' \| 'contains' \| 'endsWith'`	`'contains'`	Modalità di matching del filtro
`filterPlaceholder`	`string`	locale	Placeholder del campo filtro (default da i18n `form.searchPlaceholder`)
`filterFields`	`string[]`	`null`	Campi su cui applicare il filtro
`filterLocale`	`string`	`null`	Locale per il confronto stringhe nel filtro
`showClear`	`boolean`	`false`	Mostra pulsante per azzerare la selezione
`checkmark`	`boolean`	`false`	Mostra checkmark accanto all'opzione selezionata (single)
`editable`	`boolean`	`false`	Permette di digitare testo libero oltre alle opzioni
`fluid`	`boolean`	`true`	Occupa tutta la larghezza disponibile
`selectOnFocus`	`boolean`	`false`	Seleziona automaticamente l'opzione al focus
`virtualScrollerOptions`	`{ itemSize?: number } \| null`	`null`	Configurazione del virtual scroller per liste molto lunghe. Impostando `itemSize` (altezza in px di ogni opzione) si attiva la virtualizzazione (row windowing), che riduce i nodi DOM renderizzati. Non compatibile con le opzioni raggruppate
`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 (confronto oggetti)
`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
`autoFilterFocus`	`boolean`	`false`	Focus automatico sul filtro all'apertura
`resetFilterOnHide`	`boolean`	`false`	Resetta il filtro alla chiusura del dropdown
`highlightOnSelect`	`boolean`	`true`	Evidenzia l'opzione selezionata nella lista
`focusOnHover`	`boolean`	`true`	Sposta il focus all'opzione al passaggio del mouse
`autoOptionFocus`	`boolean`	`true`	Sposta il focus sulla prima opzione all'apertura
`defaultValue`	`OptionValue \| OptionValue[]`	`null`	Valore predefinito se modelValue non è fornito
`visibleOptions`	`number`	—	Numero di opzioni visibili senza scroll
`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 \| OptionValue[]`	Aggiornamento v-model
`change`	`{ originalEvent: Event, value: OptionValue \| OptionValue[], selectedOption: T \| T[] \| null }`	Cambio di selezione con dettagli completi
`filter`	`{ originalEvent: Event, value: string }`	Cambio del testo filtro
`clear`	`Event`	Selezione azzerata
`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, placeholder }`	Personalizza la visualizzazione del valore selezionato
`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

Esempi

Con filtro di ricerca

Selezione multipla

In modalità multipla il v-model è un array di valori. Le opzioni selezionate vengono mostrate come chips rimuovibili nel trigger:

Opzioni raggruppate

Varianti e dimensioni

Con pulsante clear

Stati

Editable (testo libero)

Con editable=true l'utente può inserire un valore non presente nelle opzioni:

Async / loading

Slot option personalizzato

Evento change con dettagli completi

Accessibilità

Il trigger ha role="combobox" con aria-expanded e aria-haspopup
Supporto navigazione tastiera: ArrowDown/Up naviga le opzioni, Enter/Space seleziona, Escape chiude
Type-ahead: digitando una lettera naviga direttamente all'opzione corrispondente (con dropdown chiuso seleziona direttamente)
Input nascosto associato alla label tramite id per compatibilità con form nativi
aria-label e aria-labelledby configurabili
Ogni opzione ha role="option" e aria-selected
Il trigger è escluso dal tab order quando disabled

TypeScript

SelectProps e SelectEmits sono generici sul tipo dell'opzione (default Record<string, unknown>):

import type { SelectProps, SelectEmits } from '@pzeta/vue-components'

interface City {
  id: number
  name: string
  region?: string
}

const cities: City[] = [
  { id: 1, name: 'Roma', region: 'Lazio' },
  { id: 2, name: 'Milano', region: 'Lombardia' },
]

const selected = ref<number | null>(null)

// In un wrapper generico:
type CitySelectProps = SelectProps<City>
type CitySelectEmits = SelectEmits<City>

Il payload di change include selectedOption tipizzata come T | T[] | null — utile per accedere all'oggetto completo senza ricerche manuali nell'array options.

Note

Default fluid: true — il componente per default occupa tutta la larghezza del contenitore. Imposta :fluid="false" per usare width auto.
Placeholder/filterPlaceholder via i18n — se non specificati, vengono presi da form.selectPlaceholder e form.searchPlaceholder del dizionario @pzeta/vue-i18n.
appendTo='body' — il dropdown viene teleportato sul <body> per evitare clipping da overflow. Per dropdown all'interno di overlay (Dialog, Drawer) o test e2e potresti dover usare appendTo='self'.

Rating

Componente di valutazione a stelle con numero configurabile di stelle, icone personalizzabili, modalità readonly e pulsante di annullamento.

SelectableCard

Griglia di card selezionabili come alternativa visuale a radio button e checkbox. Supporta immagini, icone, selezione singola e multipla con layout configurabile a colonne.