Rol Widget

`combobox`

Markeert een tekstinvoer gekoppeld aan een popuplijst met waarden — voor automatisch aanvullen, type-ahead zoeken en aangepaste keuzelijsten. Het native <select>-element volstaat voor eenvoudige enkelvoudige selectie; gebruik role="combobox" alleen bij filtering, aangepaste opmaak of externe suggesties.

Wanneer gebruiken

Gebruik <select> wanneer de keuze uit een korte, vaste lijst komt en de gebruiker niet hoeft te filteren. Het native element biedt mobiel-vriendelijke keuzepanelen, volledige toetsenbordondersteuning en geen JavaScript.

role="combobox" is bedoeld voor gevallen die het native element niet aankan:

Automatisch aanvullen met filtering (stadzoekopdracht, gebruikersvermelding).
Suggesties opgehaald via een externe API.
Items weergegeven met rijke inhoud (avatars, secundaire tekst).
Tag-invoervelden waarbij meerdere waarden geselecteerd kunnen worden.

ARIA 1.2 heeft het combobox-patroon ingrijpend gewijzigd. De rol wordt toegepast op het <input>-element, NIET op de wrapper. De popup is een afzonderlijke role="listbox" (of tree/grid/dialog) die de combobox via aria-controls beheert.

Toetsenbord- en focuscontract

Conform het APG-combobox-patroon:

Focus blijft te allen tijde op het invoerveld. De keuzelijst wordt geopend via aria-expanded="true" en de actieve optie wordt bijgehouden via aria-activedescendant, NIET door focus te verplaatsen.
Pijl-omlaag opent de popup en verplaatst de actieve optie naar het eerste item.
Pijl-omhoog en pijl-omlaag verplaatsen de actieve optie binnen de popup.
Enter selecteert de actieve optie en sluit de popup.
Escape sluit de popup; bij een tweede Escape wordt het invoerveld gewist.
Typen filtert de lijst (wanneer aria-autocomplete="list" of "both").

Stel aria-autocomplete in op "none", "inline", "list" of "both" om het suggestiegedrag te beschrijven.

Veelvoorkomende fouten

role="combobox" op de wrapper plaatsen in plaats van op het <input>-element (het pre-1.2-patroon). Moderne schermlezers verwachten de rol op het bewerkbare element.
DOM-focus naar de keuzelijst verplaatsen bij pijl-omlaag. APG vereist aria-activedescendant; het verplaatsen van focus verbreekt het typen.
aria-expanded blijft op "false" staan ook als de popup zichtbaar is.
Keuzelijst aanwezig in de DOM maar nooit gekoppeld via aria-controls.
Lijst filteren maar aria-activedescendant laten verwijzen naar een item dat niet meer bestaat.

Voorbeeld

<label for="city">City</label>
<input
  id="city"
  type="text"
  role="combobox"
  aria-controls="cityList"
  aria-expanded="false"
  aria-autocomplete="list"
  aria-activedescendant=""
>
<ul id="cityList" role="listbox" hidden>
  <li id="city-1" role="option">London</li>
  <li id="city-2" role="option">Lisbon</li>
  <li id="city-3" role="option">Ljubljana</li>
</ul>