aria-labelledby

Wanneer te gebruiken

Wanneer een zichtbaar stuk tekst op de pagina het element al beschrijft — een koptekst boven een dialoogvenster, een kolomkoptekst boven een cel, een alinea die een regio introduceert. aria-labelledby verwijst naar die tekst zodat de schermlezer deze aankondigt als de toegankelijke naam van het element. De gebruiker hoort precies wat een ziende gebruiker leest.

Het native HTML-equivalent is <label for="…"> op formulierinvoervelden. aria-labelledby breidt hetzelfde concept uit naar elke role die een naam ondersteunt.

Gedrag

De waarde is een door spaties gescheiden lijst van element-ID’s. Hulptechnologie verzamelt de tekstinhoud van elk verwezen element, in volgorde, voegt ze samen met spaties en gebruikt het resultaat als de toegankelijke naam. Verwijzingen naar verborgen elementen (display: none, hidden) leveren nog steeds hun tekst — het element hoeft alleen maar in de DOM aanwezig te zijn.

aria-labelledby heeft voorrang op aria-label, dat op zijn beurt voorrang heeft op zichtbare interne tekst. Als naar de zichtbare koptekst wordt verwezen, is een extra aria-label niet nodig.

Om de relatie geldig te houden: de verwezen ID’s moeten op de pagina bestaan, uniek zijn, en de tekst erin moet betekenisvol blijven. Als een tabpaneel opnieuw wordt gerenderd en ID’s worden hergebruikt, controleer dan of de nieuwe inhoud het gelabelde element nog steeds correct beschrijft.

Veelvoorkomende fouten

• Verwijzen naar een ID die niet bestaat (typefout, element verwijderd, component ontkoppeld). De relatie mislukt stilzwijgend en het element blijft naamloos.
• Dezelfde ID tweemaal op de pagina gebruiken — alleen de eerste overeenkomst telt.
• Verwijzen naar een element waarvan de tekst leeg of uitsluitend witruimte is.
• Aaneenschakeling in de verkeerde volgorde: aria-labelledby="achternaam voornaam" levert “Jansen Jan” op wanneer “Jan Jansen” bedoeld was.
• Verwijzen naar een generieke <div> met een lange alinea — de hele alinea wordt de naam. Namen moeten kort zijn; uitgebreide context hoort in aria-describedby.
• Vergeten de verwezen tekst bij te werken bij lokalisatie — namen raken dan niet gesynchroniseerd met de zichtbare interface.

Voorbeeld

<h2 id="billing-heading">Factuuradres</h2>
<div role="group" aria-labelledby="billing-heading">
  <label>
    Straat
    <input type="text" autocomplete="street-address">
  </label>
  <!-- … -->
</div>

<!-- Twee ID's aaneengeschakeld voor een "voor- + achternaam"-patroon -->
<span id="first">Voornaam</span>
<span id="last">(verplicht)</span>
<input type="text" aria-labelledby="first last">