Forms

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.

Import

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

Esempio Base

Props

Prop	Tipo	Default	Descrizione
`modelValue`	`ListboxOptionValue \| ListboxOptionValue[]`	`undefined`	Valore selezionato (v-model)
`options`	`ListboxOption[] \| ListboxOptionGroup[]`	`[]`	Array di opzioni o gruppi
`optionLabel`	`string \| ((o) => string)`	`null`	Proprietà o funzione per il testo visualizzato
`optionValue`	`string \| ((o) => ListboxOptionValue)`	`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) => ListboxOption[])`	`null`	Proprietà con le opzioni figlie del gruppo
`multiple`	`boolean`	`false`	Abilita selezione multipla con checkbox
`filter`	`boolean`	`false`	Mostra campo di ricerca nella lista
`filterMatchMode`	`'startsWith' \| 'contains' \| 'endsWith'`	`'contains'`	Modalità di matching del filtro
`filterPlaceholder`	`string`	`'Search...'`	Placeholder del campo filtro
`filterLocale`	`string`	`null`	Locale per il confronto stringhe nel filtro
`filterFields`	`string[]`	`null`	Campi su cui applicare il filtro
`checkmark`	`boolean`	`false`	Mostra checkmark accanto all'opzione selezionata (single)
`highlightOnSelect`	`boolean`	`true`	Evidenzia le opzioni selezionate
`metaKeySelection`	`boolean`	`false`	Richiede Meta/Ctrl per selezione multipla senza checkbox
`scrollHeight`	`string`	`'14rem'`	Altezza massima della lista con scroll
`listStyle`	`string \| Record<string, string \| number>`	`null`	Stile inline per il contenitore lista
`striped`	`boolean`	`false`	Righe alternate con sfondo alternato
`label`	`string`	`null`	Label mostrata sopra la lista
`helperText`	`string`	`null`	Testo di aiuto sotto la lista
`error`	`string`	`null`	Messaggio di errore
`invalid`	`boolean`	`false`	Stato di validazione invalido
`disabled`	`boolean`	`false`	Disabilita il componente
`required`	`boolean`	`false`	Campo obbligatorio
`size`	`'small' \| 'medium' \| 'large'`	`'medium'`	Dimensione del componente
`dataKey`	`string`	`null`	Chiave univoca per il confronto di oggetti
`name`	`string`	`null`	Nome per i form nativi
`ariaLabel`	`string`	`null`	Aria label per screen reader
`ariaLabelledby`	`string`	`null`	ID dell'elemento label ARIA
`autoOptionFocus`	`boolean`	`true`	Focus automatico sulla prima opzione
`focusOnHover`	`boolean`	`true`	Sposta il focus all'opzione al passaggio del mouse
`selectOnFocus`	`boolean`	`false`	Seleziona automaticamente l'opzione al focus da tastiera
`defaultValue`	`ListboxOptionValue \| ListboxOptionValue[]`	`null`	Valore predefinito
`filterInputProps`	`Record<string, unknown>`	`null`	Attributi aggiuntivi per l'input di filtro

Emits

Evento	Payload	Descrizione
`update:modelValue`	`ListboxOptionValue \| ListboxOptionValue[]`	Aggiornamento v-model
`change`	`{ originalEvent: Event, value: ListboxOptionValue \| ListboxOptionValue[] }`	Cambio di selezione
`value-change`	`ListboxOptionValue \| ListboxOptionValue[]`	Cambio valore (alias semplificato)
`filter`	`{ originalEvent: Event, value: string, filterValue: unknown[] }`	Cambio del testo filtro
`focus`	`Event`	La lista riceve il focus
`blur`	`Event`	La lista perde il focus
`item-dblclick`	`{ originalEvent: Event, value: ListboxOptionValue }`	Doppio click su un'opzione
`option-dblclick`	`{ originalEvent: Event, value: ListboxOptionValue }`	Alias di item-dblclick

Slot

Slot	Scope	Descrizione
`header`	`{ value, options }`	Contenuto in cima alla lista
`footer`	`{ value, options }`	Contenuto in fondo alla lista
`option`	`{ option, selected, index }`	Template per ogni singola opzione
`optiongroup`	`{ option, index }`	Template per l'intestazione del gruppo
`empty`	—	Messaggio quando non ci sono opzioni
`emptyfilter`	—	Messaggio quando il filtro non produce risultati
`content`	`{ items, styleClass, contentRef, getItemOptions }`	Override completo del contenuto della lista
`loader`	`{ options }`	Stato di caricamento
`filtericon`	`{ class: string }`	Icona di ricerca personalizzata

Esempi

Selezione multipla

In modalità multipla ogni opzione ha una checkbox. Il v-model è un array:

Con filtro di ricerca

Con checkmark (selezione singola)

Opzioni raggruppate

Righe alternate

Con slot option personalizzato

<Listbox v-model="selected" :options="users" option-label="name">
  <template #option="{ option, selected }">
    <div class="flex items-center gap-3">
      <img :src="option.avatar" class="w-8 h-8 rounded-full" />
      <div>
        <div class="font-medium">{{ option.name }}</div>
        <div class="text-xs text-gray-500">{{ option.email }}</div>
      </div>
      <span v-if="selected" class="ml-auto text-primary-600">✓</span>
    </div>
  </template>
</Listbox>

Doppio click per azione rapida

<Listbox
  v-model="selected"
  :options="options"
  option-label="name"
  @item-dblclick="({ value }) => openDetail(value)"
/>

Stati

Accessibilità

Il contenitore lista ha role="listbox" con aria-multiselectable in modalità multipla
Supporto navigazione tastiera: ArrowDown/Up naviga le opzioni, Enter/Space seleziona, Home/End per primo/ultimo elemento
Ogni opzione ha role="option" con aria-selected e aria-disabled
L'input di filtro supporta navigazione con ArrowDown/Up ed Enter
aria-label e aria-labelledby configurabili

TypeScript

import type { ListboxProps, ListboxEmits, ListboxChangeEvent } from '@pzeta/vue-components'

function onChange(event: ListboxChangeEvent) {
  // event.value contiene il nuovo valore o array di valori
  console.log(event.value)
}

IntervalInput

Input per intervalli di tempo PostgreSQL (tipo interval). Mostra campi numerici per ogni unita di tempo (anni, mesi, giorni, ore, minuti, secondi) e serializza in formato PostgreSQL interval.

MultiSelect

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