ARIA-rollen, -statussen en -eigenschappen

Een live-regio die een urgente, tijdkritische melding overbrengt. Schermlezers kondigen deze onmiddellijk aan en onderbreken de lopende spraak. Gebruik spaarzaam — reserveer voor echte fouten en waarschuwingen; misbruik veroorzaakt vermoeidheid bij hulptechnologiegebruikers.

Een dialoogvenster dat een urgente melding overbrengt en een gebruikersreactie vereist. Combineert dialoogvenster-semantiek met een assertieve aankondiging. Gebruik alleen voor destructieve bevestigingen, blokkerende fouten of onderbrekingen die niet kunnen wachten.

Markeert een op zichzelf staande compositie die onafhankelijk zou kunnen bestaan — een blogpost, nieuwsbericht, forumreactie of productkaart. Gebruik het native <article>-element eerst; kies role="article" alleen als het HTML-element niet kan worden gebruikt.

Native HTML: <article>

Het sitewijde header-landmark — bevat doorgaans het logo, de primaire navigatie en zoeken. Het bovenste <header>-element draagt deze rol automatisch. Slechts één banner per pagina.

Native HTML: <header> (top-level)

Markeert een element als knop — een bedieningselement dat een actie uitvoert bij activering. Gebruik bij voorkeur het native HTML-element <button>; gebruik role="button" op een <div> of <span> alleen als het native element echt niet beschikbaar is.

Native HTML: <button>

Markeert een element als twee- of drietoestandsaankruisvakje. Gebruik <input type="checkbox"> bij voorkeur; kies voor role="checkbox" alleen als het native element niet beschikbaar is — bijvoorbeeld bij een drietoestandsbediening met een gemengde waarde.

Native HTML: <input type="checkbox">

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.

Native HTML: <select>

Een landmark voor inhoud die de hoofdinhoud ondersteunt maar op zichzelf betekenisvol is — zijbalken, gerelateerde-artikelvensters, aanvullende uitroepblokken. Het <aside>-element draagt deze rol wanneer het op het hoogste niveau staat.

Native HTML: <aside>

Het sitewijde voettekst-landmark — auteursrechtinformatie, contactgegevens, juridische koppelingen. Het bovenste <footer>-element draagt deze rol automatisch. Slechts één contentinfo per pagina.

Native HTML: <footer> (top-level)

Markeert een element als de definitie van een term. Combineer met role="term" (of natief <dfn>) om de term aan de definitie te koppelen. Gebruik bij voorkeur natief <dl>/<dt>/<dd> of <dfn> — die bevatten de semantiek al van zichzelf.

Native HTML: <dfn>

Markeert een container als modaal of niet-modaal dialoogvenster. Gebruik het native <dialog>-element met showModal() — dat verzorgt focusvangst, de top-layer, de achtergrond en Escape-om-te-sluiten gratis. Grijp naar role="dialog" alleen wanneer het native element onmogelijk is.

Native HTML: <dialog>

Markeert een op zichzelf staand illustratief blok — afbeelding, diagram, codeoverzicht — doorgaans gecombineerd met een onderschrift. Gebruik eerst het native <figure>-element; grijp naar role="figure" alleen wanneer het hostelement geen <figure> kan zijn.

Native HTML: <figure>

Een landmark voor een formulier — een verzameling invoerbesturingselementen die gegevens indienen. Een <form>-element wordt als form-landmark weergegeven ALLEEN wanneer het een toegankelijke naam heeft. Zonder naam is het slechts een formulier, geen landmark.

Native HTML: <form aria-label>

Markeert een generieke groepering van verwante elementen. Semantisch minder zwaar dan een landmark — schermlesers adverteren groepen niet in het landmarkmenu. Gebruik <fieldset> + <legend> voor gegroepeerde formulierbesturingselementen; grijp naar role="group" voor niet-formuliergroeperingen.

Native HTML: <fieldset>

Markeert een element als koptekst. Gebruik bij voorkeur <h1>–<h6> — die dragen de juiste semantiek en een correct niveau. Gebruik role="heading" alleen wanneer een element niet als <h*> kan worden gemarkeerd.

Native HTML: <h1> – <h6>

Markeert een element als hyperlink — een element dat bij activering naar een nieuwe bron navigeert. Gebruik bij voorkeur het native HTML-element <a href>; gebruik role="link" op een <span> of <div> alleen wanneer het native element absoluut niet mogelijk is.

Native HTML: <a href>

Markeert een element als een lijst van items. Gebruik bij voorkeur <ul>, <ol> of <dl> — het native element regelt de rol, het aantal en de visuele markering. Gebruik role="list" alleen als CSS list-style: none Safari's heuristiek voor het verwijderen van de lijstrol activeert.

Native HTML: <ul> / <ol>

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.

Native HTML: <select> (single-select)

Markeert een element als één item in een lijst. Gebruik <li> binnen <ul> of <ol> — het native element draagt de rol en de positie in de reeks. Gebruik role="listitem" alleen in combinatie met een expliciet role="list" op een niet-lijst-ouder.

Native HTML: <li>

Het landmark voor hoofdinhoud — de primaire inhoud van de pagina, exclusief herhaalde kopteksten, navigatie en voetteksten. Het element <main> draagt deze rol automatisch. Precies één main per pagina.

Native HTML: <main>

Markeert een container als een toepassingsmenu — de popup van Bestand/Bewerken-stijlmenu's of contextmenu's. Er is geen HTML-equivalent. Een sitenavigatielijst is GEEN menu; gebruik daarvoor <nav> met <ul> van links.

Markeert een container als een permanente menubalk — de altijd zichtbare horizontale strook met Bestand/Bewerken/Beeld-stijlmenu's zoals in desktoptoepassingen. Verschilt van menu, dat een popup is. Op het web vrijwel nooit het juiste patroon.

Markeert een element als een uitvoerbaar item binnen een menu of menubalk. Er is geen HTML-equivalent — menu's zijn een ARIA-exclusief construct. Gebruik deze rol alleen bij een echt menu (toepassingsstijl); een gewone navigatielijst mag GEEN menu/menuitem gebruiken.

Een landmark dat een set navigatielinks groepeert — primaire navigatie, broodkruimelpad, inhoudsopgave. Het <nav>-element draagt deze rol automatisch. Meerdere nav-elementen per pagina zijn normaal, maar elk moet een onderscheidende toegankelijke naam hebben.

Native HTML: <nav>

Markeert een element als een selecteerbaar item in een listbox. Een option MOET een afstammeling zijn van een listbox (direct of via aria-owns). Gebruik native <option> in <select>; gebruik role="option" alleen voor een aangepaste listbox of combobox-popup.

Native HTML: <option>

Markeert een element als voortgangsindicator. Gebruik eerst <progress> — dat levert de semantiek, de deterministische weergave en de waardeattributen native. Gebruik role="progressbar" alleen wanneer het native element onvoldoende stijlmogelijkheden biedt.

Native HTML: <progress>

Markeert een element als één optie in een wederzijds exclusieve groep. Een radio MOET in een radiogroup staan (of een native fieldset). Gebruik eerst <input type="radio">; gebruik role="radio" alleen wanneer het native element niet mogelijk is.

Native HTML: <input type="radio">

Een generiek landmark voor inhoud die niet past bij banner, main, navigation, complementary of contentinfo, maar toch belangrijk genoeg is om naartoe te navigeren. Een <section> wordt een region-landmark alleen wanneer het een toegankelijke naam heeft.

Native HTML: <section aria-label>

Een landmark dat een zoekformulier groepeert. Hiermee kunnen schermlezergebruikers direct naar de sitezoekopdracht springen. Het native element <search> (HTML 2024) draagt deze rol automatisch; gebruik role="search" op een <form> voor bredere browserondersteuning.

Native HTML: <search>

Markeert een element als tekstinvoer gericht op een zoekopdracht. Gebruik eerst <input type="search"> — dat biedt een wis-knopaffordance in de meeste browsers en de zoekopdrachtsemantiek gratis. Gebruik role="searchbox" alleen op een aangepast contenteditable-zoekveld.

Native HTML: <input type="search">

Markeert een element als scheidingslijn tussen secties van inhoud of items in een samengestelde widget. Gebruik eerst <hr> voor thematische onderbrekingen in lopende tekst; gebruik role="separator" voor het scheiden van items in een menu, werkbalk of andere widget.

Native HTML: <hr>

Markeert een element als invoer die een waarde uit een bereik selecteert. Gebruik eerst <input type="range">; kies role="slider" alleen voor maatwerk — bijvoorbeeld een twee-duim-bereikkiezer, die het native element niet ondersteunt.

Native HTML: <input type="range">

Een live-regio die niet-urgente adviesinformatie overbrengt. Schermlezers kondigen wijzigingen beleefd aan — bij de volgende pauze in de spraak, zonder te onderbreken. Gebruik voor routinebevestigingen, tellingen en voortgangsupdates. Het native <output>-element draagt deze rol.

Native HTML: <output>

Markeert een element als een aan/uit-schakelaar. Functioneel vergelijkbaar met een selectievakje, maar aangekondigd als "schakelaar, aan" of "schakelaar, uit" in plaats van "aangevinkt" — past beter bij een instellingsschakelaar. Er is nog geen native HTML-equivalent.

Markeert een element als één tab in een tabblad­interface. Een tab MOET binnen een tablist staan en ZOU MOETEN verwijzen naar het bijbehorende tabpanel via aria-controls. Er is geen native HTML-tab­element — tabs zijn een puur ARIA-patroon.

Markeert een container als de tabrij in een tabblad­interface. Bevat role="tab"-kinderen. Tabs en tabpanels zijn een puur ARIA-patroon — er is geen native HTML-tablist.

Markeert het inhoudspaneel dat bij een tab hoort. Elk tabpanel wordt gelabeld door de bijbehorende tab via aria-labelledby; de tab verwijst naar het paneel via aria-controls. Toon één paneel tegelijk; verberg de overige met het hidden-attribuut.

Markeert een element als enkelvoudige of meervoudige tekstinvoer. Gebruik eerst <input type="text"> of <textarea> — zij regelen elk tekstbox­gedrag automatisch. Kies role="textbox" alleen voor een rich-text­editor op een contenteditable-element.

Native HTML: <input type="text"> / <textarea>

Markeert een container als werkbalk — een gegroepeerde set gerelateerde bedieningselementen (een opmaakbalk, een rij met pictogramknoppen). Vermindert het aantal tab-stops: tien knoppen worden één tab-stop; pijltjestoetsen bewegen tussen de knoppen.

Markeert een element als hiërarchische container van treeitems — een bestandsverkenner, geneste categorieën of organigram. Één tab-stop, navigatie via pijltjestoetsen, uitvouwen/samenvouwen. Er is geen native HTML-equivalent.

Markeert een element als één item in een boom. Een treeitem kan uitvouwbaar zijn (ouder van meer treeitems) of terminaal (een blad). Gebruik dit alleen voor een hiërarchische navigator — bestandsverkenner, organigram, geneste categorieën — die pijltjesnavigatie met één tab-stop vereist.

Bepaalt of hulptechnologie bij een update de volledige inhoud van een live-regio aankondigt of alleen het gewijzigde deel. Standaard is "false" (alleen de diff). Stel in op "true" wanneer de context alleen als gehele zin betekenis heeft.

Markeert een regio als bezig met bijwerken zodat hulptechnologie tussentijdse aankondigingen onderdrukt. Stel in op "true" tijdens laden of grote DOM-wijzigingen; zet terug op "false" zodra de regio stabiel is.

Geeft de huidige aangevinkte toestand aan van een aankruisvakje, keuzerondje of menu-item met aanvinkoptie. Accepteert "true", "false" of "mixed". Het native HTML-aankruisvakje beheert dit automatisch — stel het alleen handmatig in op aangepaste widgets.

Markeert het element dat het huidige item in een set vertegenwoordigt — de actieve pagina in een nav, de huidige stap in een wizard, de datum van vandaag in een datumkiezer. Specifieker dan aria-selected; gebruik het op koppelingen en items waarbij selectie niet de juiste metafoor is.

Geeft aan dat een besturingselement zichtbaar en focusbaar is maar niet reageert op gebruikersinvoer. Gebruik bij voorkeur het native HTML-attribuut disabled; grijp naar aria-disabled wanneer het element focusbaar moet blijven of een tooltip moet ontvangen.

Geeft aan of een inklapbaar element — openingsknop, keuzelijst, menu, treeitem — momenteel open is. Neemt "true" of "false" als waarde. Doorgaans gecombineerd met aria-controls dat wijst naar de regio die het besturingselement opent.

Verwijdert een element en al zijn nakomelingen uit de toegankelijkheidsstructuur. Ziende gebruikers zien het element nog steeds; hulptechnologie bereikt het nooit. Gebruik uitsluitend voor decoratieve inhoud; nooit toepassen op een focusbaar element.

Geeft aan dat een formulierelement de validatie niet heeft doorstaan. Combineer met aria-describedby die verwijst naar het leesbare foutbericht, zodat de schermlezer zowel de ongeldige toestand als de reden aankondigt.

Markeert een regio waarvan updates door hulptechnologie worden aangekondigd zonder de focus te verplaatsen. Kies "polite" voor de meeste gevallen, "assertive" voor echt urgente updates. De regio moet bij de initiële render in de DOM aanwezig zijn.

Geeft hulptechnologie aan de rest van de pagina als inert te behandelen terwijl een dialoogvenster open is. Stel in op "true" voor role="dialog" of role="alertdialog". Maakt de achtergrond zelf niet inert — combineer altijd met het inert-attribuut of een focustrap.

Geeft aan of een schakelknop momenteel ingedrukt is. Stel in op "true" wanneer de schakelaar aan is, "false" wanneer uit; de hulptechnologie kondigt de toestand samen met het label aan.

Geeft aan dat de waarde van een formulierbesturingselement niet bewerkbaar is, maar het element nog steeds bedienbaar is — focusbaar, kopieerbaar en meegestuurd bij het indienen. Verschilt van aria-disabled, dat het element volledig inoperabel maakt.

Geeft aan dat een item in een enkel- of meervoudig selecteerbare container momenteel geselecteerd is. Gebruikt op tab, option, gridcell, treeitem en vergelijkbare rollen. Verschilt van aria-checked (selectievakje/keuzerondje) en aria-pressed (schakelknop).

Op een samengestelde widget wijst dit naar het ID van het actieve onderliggende element. De DOM-focus blijft op de container terwijl een virtuele focus door de kinderen beweegt. Alternatief voor roving tabindex bij keuzelijsten, comboboxen en rasters.

Op een tekstvak of combobox geeft dit aan welk soort automatisch aanvullen het besturingselement biedt — inline suggesties, een keuzelijst, beide of geen. Verschilt van het HTML autocomplete-attribuut, dat over formulierveldsemantieken voor de browser gaat.

Vermeldt het element of de elementen waarvan de aanwezigheid of inhoud door dit bedieningselement wordt bepaald. Veelvoorkomende combinaties: een tab beheert zijn tabpanel, een openbaarmakingsknop beheert een onthulde regio. Ondersteuning door hulptechnologie is wisselend — gebruik spaarzaam.

Verwijst naar een of meer ID's van elementen waarvan de tekst de uitgebreide beschrijving van dit element wordt. Wordt na de toegankelijke naam aangekondigd. Gebruik voor helptekst, opmaakaanwijzingen en inline foutmeldingen.

Meldt hulptechnologie dat activering van dit element een popup opent, en van welk type. Accepteert "menu", "listbox", "tree", "grid", "dialog" of "true" / "false". Combineer met aria-expanded zodat hulptechnologie ook de open/gesloten-toestand kan aankondigen.

Biedt een toegankelijke naam als tekenreeks wanneer er geen zichtbare tekst beschikbaar is. Gebruik alleen wanneer er geen zichtbaar label op het scherm staat — als er zichtbare tekst aanwezig is, verdient aria-labelledby de voorkeur zodat de uitgesproken naam overeenkomt met wat de gebruiker ziet.

Verwijst naar een of meer element-ID's waarvan de zichtbare tekst de toegankelijke naam van dit element wordt. Verdient de voorkeur boven aria-label wanneer er al tekst op het scherm staat die het element beschrijft.

Geeft het hiërarchische niveau van een element binnen een structuur aan. Verplicht op role="heading"-elementen; ook gebruikt op role="treeitem" en role="listitem" in geneste lijsten. Gehele getalswaarde, beginnend bij 1.

Declareert een ouder-kindrelatie in de toegankelijkheidsstructuur wanneer de DOM-structuur dat niet uitdrukt. Reparenteert de gerefereerde elementen als kinderen van dit element voor hulptechnologie. Een krachtig hulpmiddel — gemakkelijk te misbruiken.

Positie van een item in een set wanneer de DOM dit niet kan uitdrukken — doorgaans omdat items gevirtualiseerd, gepagineerd of gefilterd zijn. Combineer altijd met aria-setsize zodat schermlezers "3 van 47" kunnen aankondigen.

Geeft aan dat gebruikersinvoer vereist is op een besturingselement voordat een formulier kan worden ingediend. Gebruik het HTML-attribuut required op native formuliervelden; gebruik aria-required alleen wanneer geen HTML-equivalent beschikbaar is — bijv. een combobox gebouwd op een div.

Totaal aantal items in een reeks wanneer de DOM ze niet allemaal bevat. Gecombineerd met aria-posinset zodat een schermlezer "item 14 van 5.000" kan aankondigen, ook als slechts vijf items zijn gerenderd. Gebruik -1 als het totaal onbekend is.

Kondigt op een kolom- of rij­kopregel in een sorteerbare grid of tabel de huidige sorteerrichting aan. Waarden: "ascending", "descending", "other" of "none". Slechts één kopregel per tabel mag tegelijk een gesorteerde waarde dragen.

Huidige numerieke waarde van een bereikwidget — slider, progressbar, spinbutton, scrollbar. Combineer met aria-valuemin en aria-valuemax zodat hulptechnologie een zinvolle positie kan aankondigen. Gebruik aria-valuetext voor niet-numerieke labels.