Element.ariaLevel — Eigenschaft · JavaScript-Referenz

Signatur

Element.ariaLevel

Beschreibung

Die Eigenschaft ariaLevel gehört zur ARIA-Reflexion (ARIAMixin) der Schnittstelle Element. Sie spiegelt das HTML-Attribut aria-level direkt wider: Wenn du die Eigenschaft liest, erhältst du den Attributwert. Wenn du sie setzt, wird das Attribut geändert. Setzt du sie auf null, wird das Attribut entfernt.

aria-level gibt die Ebene eines Elements in einer Hierarchie an. Die Zählung beginnt bei 1. Das Attribut wird vor allem bei diesen Rollen verwendet:

role="heading": eigene Überschriften, wenn keine echten Elemente <h1>–<h6> genutzt werden können. Ebenen über 6 sind erlaubt, werden aber nicht von jedem Screenreader unterstützt.
role="treeitem": die Verschachtelungstiefe in einer Baumansicht, wenn sie nicht aus dem DOM abgeleitet werden kann.
role="row" in einem treegrid, außerdem listitem in verschachtelten Listen.

Die Eigenschaft ist nützlich, wenn Komponenten (z. B. Web Components oder virtualisierte Baumansichten) die Hierarchie per Skript aufbauen. Dann kannst du die Ebene ohne setAttribute() setzen. Der Wert ist immer ein String und keine Zahl.

Parameter

Name	Typ	Default	Beschreibung
$value (beim Setzen)	string \| null		Eine positive Ganzzahl als String, z. B. `"2"`. Mit `null` wird das Attribut `aria-level` entfernt.

Rückgabewert

Typ

string | null

Beschreibung

Der aktuelle Wert von aria-level als String, oder null, wenn das Attribut nicht gesetzt ist.

Beispiele

Ebene einer eigenen Überschrift lesen und ändern

// HTML: <div id="titel" role="heading" aria-level="1">Kapitel</div>
const titel = document.getElementById('titel');

console.log(titel.ariaLevel);          // "1"

titel.ariaLevel = '2';
console.log(titel.getAttribute('aria-level'));

1 2

Baumansicht: Ebenen per Skript vergeben

const daten = [
  { label: 'src', tiefe: 1 },
  { label: 'components', tiefe: 2 },
  { label: 'Button.js', tiefe: 3 },
];

const baum = document.createElement('ul');
baum.role = 'tree';

for (const { label, tiefe } of daten) {
  const eintrag = document.createElement('li');
  eintrag.role = 'treeitem';
  eintrag.ariaLevel = String(tiefe); // immer als String setzen
  eintrag.textContent = label;
  eintrag.style.paddingLeft = `${(tiefe - 1) * 1.5}rem`;
  baum.append(eintrag);
}

document.body.append(baum);
console.log([...baum.children].map((el) => el.ariaLevel));

["1", "2", "3"]

Ebene mit Zahlen verrechnen und Attribut entfernen

const item = document.querySelector('[role="treeitem"]');

// Der Wert ist ein String, also vor dem Rechnen umwandeln
const ebene = Number(item.ariaLevel ?? 1);
item.ariaLevel = String(ebene + 1);
console.log(item.ariaLevel);

// Attribut vollständig entfernen
item.ariaLevel = null;
console.log(item.hasAttribute('aria-level'));

2 false

// Wichtig · Fallstricke

String statt Zahl: Die Eigenschaft liefert immer einen String. Ein Ausdruck wie el.ariaLevel + 1 hängt die Zahl an den Text an: Aus "2" wird "21". Wandle den Wert deshalb vorher mit Number() um.
Keine Prüfung: Der Browser prüft den Wert nicht. "0", negative Zahlen oder Text werden unverändert gesetzt, aber von Hilfstechnologien ignoriert oder falsch gedeutet.
Native Elemente zuerst: Verwende möglichst echte Elemente <h1>–<h6>. aria-level ändert nur die Semantik für Hilfstechnologien, nicht das Aussehen oder Verhalten des Elements.
Kompatibilität: Firefox unterstützt die ARIA-Reflexion erst ab Version 119. Für ältere Browser ist setAttribute('aria-level', '2') die sichere Alternative. Der Wert muss zur Rolle passen, sonst hat er keine Wirkung.

Siehe auch

Element.role CSSMathNegate.value Element.ariaInvalid Element.ariaLabel Element.ariaLive