Rolle Dokumentstruktur

`listitem`

Kennzeichnet ein Element als einzelnes Element in einer Liste. Innerhalb von <ul> oder <ol> sollte <li> verwendet werden — das native Element trägt die Rolle und die Position-in-Set. role="listitem" kommt nur zum Einsatz, wenn es mit einem expliziten role="list" auf einem Nicht-Listen-Elternelement kombiniert wird.

Wann zu verwenden

Innerhalb eines <ul> oder <ol> sollte einfach <li> verwendet werden. Der Browser legt die Rolle, die Anzahl und die Position-in-Set automatisch offen.

Der einzige praktische Einsatzfall für role="listitem" besteht, wenn role="list" auf ein Nicht-Listen-Element angewendet wurde (zum Beispiel, um die list-style: none-Heuristik von Safari zu umgehen) und die darin enthaltenen Elemente ebenfalls keine Listenelemente sind. In diesem Fall benötigt jedes Element role="listitem", damit es mitgezählt wird.

Ein Listitem MUSS sich innerhalb eines role="list" befinden. Ein einzelnes role="listitem" ohne Listen-Elternelement ist ungültig und wird von Screenreadern ignoriert.

Häufige Fehler

role="listitem" auf einem <div>, dessen Elternelement kein role="list" ist. Das Listitem hat keinen Gruppenkontext.
<li> außerhalb von <ul> / <ol>. Ungültiges HTML.
Setzen von aria-posinset und aria-setsize, obwohl die DOM-Hierarchie die Position bereits widerspiegelt. Redundant.
Verwechslung von role="listitem" mit role="option" (das innerhalb von role="listbox" für auswählbare Elemente verwendet wird).
Hinzufügen von role="listitem" zu <li>-Elementen, die sich bereits innerhalb eines <ul> befinden — doppelte Rolle, kein Effekt.

Beispiel

<!-- Bevorzugt -->
<ul>
  <li>JAWS</li>
  <li>NVDA</li>
  <li>VoiceOver</li>
</ul>

<!-- Nicht-Listen-Container mit expliziten Rollen -->
<div role="list" aria-label="Recent updates">
  <div role="listitem">New /toolkit/standards/ landing page</div>
  <div role="listitem">WCAG 2.2 reference complete</div>
</div>