Rol Samengestelde widget

`listbox`

Markeert een element als een lijst met selecteerbare opties. Gebruik <select> voor het eenvoudige enkelvoudige geval — dat biedt een mobiel-vriendelijke kiezer met volledige toetsenbordondersteuning. Gebruik role="listbox" voor aangepaste opmaak, meervoudige selectie of koppeling met een combobox.

Wanneer te gebruiken

Gebruik waar mogelijk <select> (enkelvoudige selectie) of <select multiple>. Het native element levert het volledige interactiemodel, inclusief platformcorrecte toetsenbordafhandeling.

role="listbox" is geschikt wanneer:

De listbox de popup is van een aangepaste combobox.
Rijke optie-inhoud nodig is (pictogrammen, secundaire tekst) die <select> niet kan weergeven.
Meervoudige selectie met aangepaste vinkstijl nodig is.
Een transferlijst of filterbare kiezer wordt gebouwd.

Kinderen moeten role="option" zijn (met role="group" als tussenliggende wrapper voor secties). Stel aria-multiselectable="true" in voor listboxen met meervoudige selectie.

Toetsenbord- en focuscontract

Volgens het APG listbox-patroon:

Tab verplaatst de focus naar de listbox; Tab verplaatst de focus eruit. Binnen de listbox blijft de focus op de container en wordt de “actieve” optie bijgehouden via aria-activedescendant.
Pijl omhoog/omlaag verplaatst de actieve optie.
Home / End springt naar de eerste / laatste optie.
Enkelvoudige selectie: elke pijldruk selecteert ook de actieve optie.
Meervoudige selectie: Spatie schakelt selectie op de actieve optie; Shift+Pijl breidt een aaneengesloten bereik uit; Ctrl/Cmd+A selecteert alles.
Typeahead: het typen van een letter springt naar de volgende optie die met die letter begint.

Veelvoorkomende fouten

DOM-focus verplaatsen naar elke optie in plaats van aria-activedescendant te gebruiken. Verstoort typeahead en combobox-integratie.
role="option"-kinderen zonder id-attributen — aria-activedescendant kan er niet naar verwijzen.
Listbox met meervoudige selectie zonder aria-multiselectable="true". Schermlezers kondigen het aan als enkelvoudige selectie.
Listbox bevat opties die elders in de DOM staan zonder aria-owns om de relatie expliciet te maken.
role="listbox" gebruiken voor een statische lijst van alleen-lezen items. Dat is role="list", niet listbox — listbox impliceert interactiviteit.

Voorbeeld

<label id="topicsLabel">Kies uw onderwerpen</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">Toegankelijkheid</li>
  <li id="topic-2" role="option" aria-selected="false">Hulptechnologie</li>
  <li id="topic-3" role="option" aria-selected="true">Standaarden</li>
</ul>