Signatur
Beschreibung
Die Eigenschaft Element.role spiegelt das HTML-Attribut role wider. Sie gehört zum Mixin ARIAMixin, über das alle ARIA-Attribute als DOM-Eigenschaften verfügbar sind (z. B. ariaLabel, ariaExpanded). Wenn Sie element.role lesen, erhalten Sie denselben Wert wie mit element.getAttribute("role"). Wenn Sie die Eigenschaft setzen, wird das Attribut im DOM geändert.
Die Eigenschaft liefert nur die explizit gesetzte Rolle. Die implizite Rolle eines Elements, etwa button bei einem <button> oder navigation bei <nav>, gibt sie nicht zurück. Ohne role-Attribut ist der Wert null. Die tatsächlich berechnete Rolle sehen Sie im Barrierefreiheits-Baum der Entwicklerwerkzeuge.
Typische Anwendungsfälle sind eigene Bedienelemente wie Tabs, Menüs, Schalter oder Dialoge aus <div>-Elementen und Tests zur Barrierefreiheit. Nutzen Sie trotzdem zuerst native HTML-Elemente. ARIA-Rollen ändern nur die Semantik für Hilfstechnologien, nicht das Verhalten: Tastaturbedienung und Fokus müssen Sie selbst umsetzen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $wert | string | null | Beim Setzen: eine oder mehrere durch Leerzeichen getrennte ARIA-Rollen (z. B. "switch checkbox"). Die erste unterstützte Rolle gilt, die anderen sind Rückfallwerte. null entfernt das Attribut. |
Rückgabewert
role-Attributs als Zeichenkette oder null, wenn kein Attribut gesetzt ist. Der Wert wird nicht geprüft und nicht normalisiert.Beispiele
Explizite und implizite Rolle auslesen
document.body.innerHTML = `
<div id="hinweis" role="alert">Gespeichert!</div>
<button id="senden">Senden</button>
`;
const hinweis = document.getElementById('hinweis');
const senden = document.getElementById('senden');
console.log(hinweis.role); // explizit gesetzt
console.log(senden.role); // nur implizite Rolle -> nullEigenen Umschalter barrierefrei machen
const schalter = document.createElement('div');
schalter.textContent = 'Dunkelmodus';
schalter.role = 'switch';
schalter.ariaChecked = 'false';
schalter.tabIndex = 0;
const umschalten = () => {
const an = schalter.ariaChecked === 'true';
schalter.ariaChecked = String(!an);
document.documentElement.classList.toggle('dark', !an);
};
schalter.addEventListener('click', umschalten);
schalter.addEventListener('keydown', (e) => {
if (e.key === ' ' || e.key === 'Enter') {
e.preventDefault();
umschalten();
}
});
document.body.append(schalter);
console.log(schalter.outerHTML);Rolle entfernen und mit Rückfall für ältere Browser setzen
const el = document.querySelector('#tabliste') ?? document.createElement('div');
// Fallback, falls die Eigenschaft fehlt (z. B. Firefox < 119)
const setzeRolle = (element, rolle) => {
if ('role' in element) {
element.role = rolle;
} else if (rolle === null) {
element.removeAttribute('role');
} else {
element.setAttribute('role', rolle);
}
};
setzeRolle(el, 'tablist');
console.log(el.getAttribute('role'));
setzeRolle(el, null);
console.log(el.hasAttribute('role'));// Wichtig · Fallstricke
- Keine implizite Rolle:
element.roleliefert bei<button>,<nav>und ähnlichen Elementen ohne Attributnull. Für die berechnete Rolle gibt es noch keine standardisierte DOM-API. Prüfen Sie sie in den Entwicklerwerkzeugen oder mit Test-Werkzeugen, z. B.getByRoleaus der Testing Library. - Keine Prüfung: Ungültige Werte wie
"knopf"werden ohne Fehler gespeichert, aber von Hilfstechnologien ignoriert. - Nur Semantik: Eine Rolle wie
buttonmacht ein Element weder fokussierbar noch per Tastatur bedienbar. Dafür brauchen SietabIndexund eigene Tastatur-Handler. Falsche Rollen schaden der Barrierefreiheit mehr als fehlende Rollen („Kein ARIA ist besser als schlechtes ARIA“). - Browser-Unterstützung: Chromium und Safari unterstützen die Eigenschaft seit Längerem, Firefox erst ab Version 119. Für ältere Umgebungen oder jsdom (je nach Version) greifen Sie auf
setAttribute("role", …)undgetAttribute("role")zurück. - Bei Custom Elements können Sie die Standardrolle über
ElementInternals.rolefestlegen, ohne das sichtbare Attribut zu verändern.