Normative · ARIA

Ruolo Widget composito

listbox

Segna un elemento come elenco di opzioni selezionabili. Per il caso semplice si utilizza <select>, che offre supporto tastiera e mobile nativo. Si ricorre a role="listbox" quando è necessario uno stile personalizzato, una selezione multipla con rendering su misura o l'abbinamento a una combobox.

Quando utilizzarlo

Ove possibile, si utilizzi <select> (selezione singola) oppure <select multiple>. L’elemento nativo fornisce l’intero modello di interazione, compresa la gestione della tastiera conforme alla piattaforma.

role="listbox" è appropriato nei seguenti casi:

  • La listbox è il pannello a comparsa di una combobox personalizzata.
  • Sono necessari contenuti di opzione complessi (icone, testo secondario) che <select> non può visualizzare.
  • È richiesta una selezione multipla con stile del segno di spunta personalizzato.
  • Si costruisce un elenco di trasferimento o un selettore filtrabile.

Gli elementi figli devono avere role="option" (con role="group" ammesso come contenitore intermedio per il raggruppamento). Per le listbox a selezione multipla si imposta aria-multiselectable="true".

Contratto tastiera e focus

Secondo il pattern APG per la listbox:

  • Tab sposta il focus sulla listbox; Tab lo sposta fuori. All’interno della listbox il focus rimane sul contenitore e l’opzione «attiva» è tracciata tramite aria-activedescendant.
  • Le frecce Su/Giù spostano l’opzione attiva.
  • Home / Fine saltano alla prima / all’ultima opzione.
  • Selezione singola: ogni pressione di una freccia seleziona anche l’opzione attiva.
  • Selezione multipla: Spazio attiva o disattiva la selezione sull’opzione attiva; Shift+Freccia estende un intervallo contiguo; Ctrl/Cmd+A seleziona tutto.
  • Digitazione anticipata: premendo una lettera si salta alla prossima opzione che inizia con quella lettera.

Errori comuni

  • Spostare il focus DOM su ciascuna opzione invece di utilizzare aria-activedescendant. Interrompe la digitazione anticipata e l’integrazione con la combobox.
  • Elementi figli role="option" privi di attributo id — aria-activedescendant non può fare riferimento a essi.
  • Listbox a selezione multipla priva di aria-multiselectable="true". Gli screen reader la annunciano come selezione singola.
  • La listbox possiede opzioni che si trovano altrove nel DOM senza utilizzare aria-owns per rendere esplicita la relazione.
  • Utilizzo di role="listbox" per un elenco statico di elementi in sola lettura. In questo caso si usa role="list", non listbox — listbox implica interattività.

Esempio

<label id="topicsLabel">Pick your topics</label>
<ul
  role="listbox"
  aria-labelledby="topicsLabel"
  aria-multiselectable="true"
  tabindex="0"
  aria-activedescendant="topic-1"
>
  <li id="topic-1" role="option" aria-selected="true">Accessibility</li>
  <li id="topic-2" role="option" aria-selected="false">Assistive tech</li>
  <li id="topic-3" role="option" aria-selected="true">Standards</li>
</ul>