ElementInternals.ariaLevel — Eigenschaft · JavaScript-Referenz

Signatur

ElementInternals.ariaLevel

Beschreibung

Die Eigenschaft ariaLevel des ElementInternals-Interfaces entspricht dem ARIA-Attribut aria-level. Sie gibt die hierarchische Ebene eines Elements innerhalb einer Struktur an – etwa die Ebene einer Überschrift (role="heading"), eines Knotens in einem Baum (treeitem), einer Zeile in einem treegrid oder eines verschachtelten Listeneintrags.

Der Unterschied zum Attribut am Element: Über ElementInternals setzt ein Web Component seine Standard-Semantik, ohne sichtbare Attribute ins Light DOM zu schreiben. Setzt der Nutzer der Komponente selbst ein aria-level-Attribut am Host-Element, hat dieses Vorrang vor dem Wert aus den Internals. So bleibt die Komponente überschreibbar, liefert aber sinnvolle Standardwerte.

Der Wert ist ein String, der eine ganze Zahl ≥ 1 enthält (z. B. "2"). Er ist nur in Verbindung mit einer passenden Rolle sinnvoll, die typischerweise ebenfalls über internals.role gesetzt wird. Man erhält das ElementInternals-Objekt über this.attachInternals() im Konstruktor eines Custom Elements.

Parameter

Name	Typ	Default	Beschreibung
$value	string \| null	null	Beim Setzen: String mit einer positiven Ganzzahl (z. B. `"1"`, `"3"`). `null` entfernt den Standardwert.

Rückgabewert

Typ

string | null

Beschreibung

Die aktuell über die Internals gesetzte Ebene als String oder null, wenn kein Wert gesetzt wurde. Ein am Host gesetztes aria-level-Attribut wird hier nicht widergespiegelt.

Beispiele

Eigene Überschriften-Komponente mit Ebene

class AppHeading extends HTMLElement {
  static observedAttributes = ['level'];

  constructor() {
    super();
    this.internals = this.attachInternals();
    this.internals.role = 'heading';
    this.internals.ariaLevel = '2'; // Standard: Ebene 2
  }

  attributeChangedCallback(name, _alt, neu) {
    if (name === 'level') {
      const level = Math.min(Math.max(parseInt(neu, 10) || 2, 1), 6);
      this.internals.ariaLevel = String(level);
    }
  }
}

customElements.define('app-heading', AppHeading);

// <app-heading level="3">Kapitel</app-heading>
const h = document.createElement('app-heading');
h.setAttribute('level', '3');
document.body.append(h);
console.log(h.internals.ariaLevel);

3

Baumknoten mit Ebene aus der Verschachtelung

class TreeNode extends HTMLElement {
  #internals = this.attachInternals();

  connectedCallback() {
    this.#internals.role = 'treeitem';
    // Ebene = Anzahl der tree-node-Vorfahren + 1
    let level = 1;
    let parent = this.parentElement?.closest('tree-node');
    while (parent) {
      level++;
      parent = parent.parentElement?.closest('tree-node');
    }
    this.#internals.ariaLevel = String(level);
    this.dataset.level = level;
  }
}

customElements.define('tree-node', TreeNode);

const root = document.createElement('tree-node');
const child = document.createElement('tree-node');
root.append(child);
document.body.append(root);
console.log(root.dataset.level, child.dataset.level);

1 2

Standardwert zurücksetzen und Attribut-Vorrang

class MyItem extends HTMLElement {
  constructor() {
    super();
    this.internals = this.attachInternals();
    this.internals.role = 'listitem';
    this.internals.ariaLevel = '1';
  }
}
customElements.define('my-item', MyItem);

const item = document.createElement('my-item');
// Das Host-Attribut überschreibt den Internals-Wert für Screenreader
item.setAttribute('aria-level', '4');
console.log(item.internals.ariaLevel); // Internals-Wert bleibt erhalten

item.internals.ariaLevel = null; // Standardwert entfernen
console.log(item.internals.ariaLevel);

1 null

// Wichtig · Fallstricke

Nur Strings: Zahlen werden zwar in Strings umgewandelt, aber es findet keine Validierung statt – Werte wie "0" oder "abc" sind ungültig und werden von assistiven Technologien ignoriert oder falsch interpretiert.
Rolle erforderlich: ariaLevel wirkt nur mit Rollen, die aria-level unterstützen (heading, treeitem, row in treegrid, listitem, comment). Ohne passende Rolle hat die Eigenschaft keinen Effekt.
Vorrang: Ein am Host-Element gesetztes aria-level-Attribut überschreibt den Internals-Wert; der Getter der Internals zeigt das nicht an.
attachInternals() darf pro Element nur einmal aufgerufen werden und funktioniert nur bei autonomen Custom Elements, sonst wird ein NotSupportedError geworfen.
Kompatibilität: Die ARIA-Reflexion über ElementInternals ist erst seit Firefox 119 und Safari 16.4 verfügbar. Für ältere Browser ggf. per Feature-Erkennung ('ariaLevel' in ElementInternals.prototype) auf setAttribute('aria-level', …) ausweichen.

Siehe auch

ElementInternals.ariaBrailleLabel ElementInternals.ariaLabel ElementInternals.ariaLive ElementInternals.ariaModal ElementInternals.ariaBusy