Forms

TreeSelect

Dropdown con struttura ad albero per selezione gerarchica. Supporta modalità single, multiple e checkbox con selezione a cascata, filtro e visualizzazione chip.

Import

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

Struttura TreeNode

Ogni nodo dell'albero è un oggetto TreeNode:

interface TreeNode {
  key?: string | number       // Chiave univoca del nodo (obbligatoria per la selezione)
  label?: string              // Testo visualizzato
  icon?: string               // Classe icona (es. 'pi pi-folder')
  data?: unknown              // Dati custom associati al nodo
  type?: string               // Tipo del nodo (per template personalizzati)
  children?: TreeNode[]       // Nodi figli
  style?: Record<string, string | number>
  class?: string
  selectable?: boolean        // Se false il nodo non è selezionabile (default: true)
  leaf?: boolean              // Se true non ha figli (anche se children è vuoto)
  expanded?: boolean          // Stato di espansione iniziale
}

Esempio Base

Valore del v-model per modalità

Il formato del v-model dipende dalla selectionMode:

single: string | number | null — la key del nodo selezionato
multiple: TreeSelectSelectionKeys — oggetto { [key]: true } per ogni nodo selezionato
checkbox: TreeSelectSelectionKeys — oggetto { [key]: { checked: boolean, partialChecked: boolean } } per ogni nodo

// single
const selected = ref<string | null>(null)

// multiple / checkbox
const selected = ref<TreeSelectSelectionKeys>({})
// dopo selezione: { 'rome': true, 'milan': true }

// checkbox con stato parziale del padre:
// { 'italy': { checked: false, partialChecked: true }, 'rome': { checked: true } }

Props

Prop	Tipo	Default	Descrizione
`modelValue`	`TreeSelectSelectionKeys \| string \| number \| null`	`null`	Valore selezionato (v-model)
`options`	`TreeNode[]`	`[]`	Array di nodi radice dell'albero
`selectionMode`	`'single' \| 'multiple' \| 'checkbox'`	`'single'`	Modalità di selezione
`display`	`'comma' \| 'chip'`	`'comma'`	Modalità di visualizzazione dei valori selezionati
`placeholder`	`string`	—	Testo quando nessun nodo è selezionato
`maxSelectedLabels`	`number`	`3`	Numero massimo di label visibili prima di mostrare il conteggio
`selectedItemsLabel`	`string`	`'{0} items selected'`	Template per il conteggio oltre maxSelectedLabels
`metaKeySelection`	`boolean`	`false`	Richiede Meta/Ctrl per la selezione multipla
`expandedKeys`	`TreeSelectExpandedKeys`	`{}`	Chiavi dei nodi espansi (v-model:expandedKeys)
`filter`	`boolean`	`false`	Mostra campo di ricerca nel dropdown
`filterPlaceholder`	`string`	—	Placeholder del campo filtro
`filterMode`	`'lenient' \| 'strict'`	`'lenient'`	Modalità filtro: lenient mostra i padri dei risultati, strict solo i match esatti
`filterBy`	`string`	`'label'`	Campo del nodo su cui applicare il filtro
`filterLocale`	`string`	—	Locale per il filtro
`label`	`string`	—	Label mostrata sopra il campo
`helperText`	`string`	—	Testo di aiuto sotto il campo
`error`	`string`	—	Messaggio di errore
`invalid`	`boolean`	`false`	Stato di validazione invalido
`disabled`	`boolean`	`false`	Disabilita il componente
`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
`loading`	`boolean`	`false`	Stato di caricamento
`showClear`	`boolean`	`false`	Mostra pulsante per azzerare la selezione
`scrollHeight`	`string`	`'20rem'`	Altezza massima del pannello dropdown
`appendTo`	`'body' \| 'self'`	`'body'`	Target Teleport del dropdown
`inputId`	`string`	—	ID dell'input per accessibilità
`ariaLabel`	`string`	—	Aria label per screen reader
`ariaLabelledby`	`string`	—	ID dell'elemento label ARIA
`autoFilterFocus`	`boolean`	`false`	Focus automatico sul filtro all'apertura
`resetFilterOnHide`	`boolean`	`false`	Resetta il filtro alla chiusura
`expandOnOpen`	`boolean`	`false`	Espande tutti i nodi all'apertura del dropdown
`loadingIcon`	`string`	—	Classe CSS icona di caricamento
`dropdownIcon`	`string`	—	Classe CSS icona dropdown
`clearIcon`	`string`	—	Classe CSS icona clear

Emits

Evento	Payload	Descrizione
`update:modelValue`	`TreeSelectSelectionKeys \| string \| number \| null`	Aggiornamento v-model
`update:expandedKeys`	`TreeSelectExpandedKeys`	Aggiornamento chiavi espanse
`change`	`{ originalEvent: Event, value }`	Cambio di selezione
`nodeSelect`	`TreeNode`	Nodo selezionato
`nodeUnselect`	`TreeNode`	Nodo deselezionato
`nodeExpand`	`TreeNode`	Nodo espanso
`nodeCollapse`	`TreeNode`	Nodo collassato
`filter`	`{ originalEvent: Event, value: string }`	Cambio del testo filtro
`clear`	`Event`	Selezione azzerata
`focus`	`FocusEvent`	Il componente riceve il focus
`blur`	`FocusEvent`	Il componente perde il focus
`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 nel trigger
`header`	—	Contenuto in cima al dropdown
`footer`	—	Contenuto in fondo al dropdown
`empty`	—	Messaggio quando non ci sono nodi
`emptyfilter`	—	Messaggio quando il filtro non produce risultati
`option`	`{ node: TreeNode, selected: boolean }`	Template per il contenuto di ogni nodo
`togglericon`	`{ node: TreeNode, expanded: boolean }`	Icona di espansione/collasso del nodo
`checkboxicon`	`{ checked: boolean, partialChecked: boolean }`	Icona checkbox del nodo
`nodeicon`	`{ node: TreeNode }`	Icona del nodo
`dropdownicon`	`{ expanded: boolean }`	Icona del dropdown personalizzata
`clearicon`	—	Icona del pulsante clear personalizzata
`loadingicon`	—	Icona di caricamento personalizzata

Esempi

Modalità checkbox con selezione a cascata

Selezionando un nodo padre tutti i figli vengono automaticamente selezionati:

Modalità multiple

Con filtro

Nodo non selezionabile

Impostare selectable: false sul nodo per renderlo non selezionabile (utile per categorie o sezioni):

const nodes: TreeNode[] = [
  {
    key: 'settings',
    label: 'Impostazioni',
    icon: 'pi pi-cog',
    selectable: false,   // Non selezionabile
    children: [
      { key: 'profile', label: 'Profilo' },
    ],
  },
]

Gestione eventi nodo

<TreeSelect
  v-model="selected"
  :options="nodes"
  @node-select="node => console.log('Selezionato:', node.label)"
  @node-unselect="node => console.log('Deselezionato:', node.label)"
  @node-expand="node => console.log('Espanso:', node.label)"
/>

Accessibilità

Il trigger ha role="combobox" con aria-expanded e aria-haspopup
Supporto navigazione tastiera: ArrowDown apre il dropdown, Enter/Space apre il dropdown, Escape chiude
aria-label e aria-labelledby configurabili
Input nascosto associato alla label per compatibilità form

TypeScript

import type {
  TreeSelectProps,
  TreeSelectEmits,
  TreeSelectSelectionKeys,
  TreeSelectExpandedKeys,
  TreeSelectChangeEvent,
} from '@pzeta/vue-components'
import type { TreeNode } from '@pzeta/vue-components'

// Selezione checkbox
const selected = ref<TreeSelectSelectionKeys>({})
// Esempio valore: { 'rome': { checked: true, partialChecked: false } }

// Selezione singola
const selectedKey = ref<string | null>(null)
// Esempio valore: 'rome'

ToggleSwitch

Interruttore on/off con icone personalizzabili, supporto per trueValue/falseValue, varianti di dimensione e severità.

Forms

Componenti form — input, select, date picker, toggle, upload e componenti speciali. 31 componenti totali.