ElementInternals.ariaHidden — Eigenschaft · JavaScript-Referenz

Signatur

ElementInternals.ariaHidden

Beschreibung

Die Eigenschaft ariaHidden der Schnittstelle ElementInternals gehört zum ARIA-Reflection-Mechanismus für autonome Custom Elements. Mit ihr legt ein Web Component intern fest, ob es im Barrierefreiheitsbaum (Accessibility Tree) auftaucht. Damit entspricht sie dem Attribut aria-hidden, erscheint aber nicht als Attribut im DOM des Host-Elements.

Gültige Werte sind die Zeichenketten "true" (Element samt Nachfahren wird für Hilfstechnologien ausgeblendet), "false", "undefined" oder null (kein Standardwert). Der Wert ist eine Standard-Semantik: Setzt ein Nutzer der Komponente selbst das Attribut aria-hidden auf dem Element, hat dieses Attribut Vorrang vor dem internen Wert.

Typische Einsatzfälle sind rein dekorative Komponenten wie Icons, Trenner, Hintergrund-Animationen oder Lade-Spinner neben einem Textlabel. Solche Elemente sollen Screenreader nicht vorlesen. Auf ElementInternals greifen Sie über this.attachInternals() im Konstruktor der Komponente zu.

Parameter

Name	Typ	Default	Beschreibung
$value	string \| null	null	Beim Setzen: `"true"`, `"false"`, `"undefined"` oder `null`. Andere Werte übernimmt der Browser zwar als Zeichenkette, ARIA wertet sie aber nicht aus.

Rückgabewert

Typ

string | null

Beschreibung

Der aktuell intern gesetzte Wert als Zeichenkette oder null, wenn nichts gesetzt ist. Ein gesetztes aria-hidden-Attribut auf dem Host-Element wird hier nicht zurückgegeben.

Beispiele

Dekoratives Icon-Element standardmäßig ausblenden

class DecoIcon extends HTMLElement {
  #internals;

  constructor() {
    super();
    this.#internals = this.attachInternals();
    // Icon ist rein dekorativ, Screenreader sollen es überspringen
    this.#internals.ariaHidden = 'true';

    const shadow = this.attachShadow({ mode: 'open' });
    shadow.innerHTML = '<svg width="16" height="16"><circle cx="8" cy="8" r="6"/></svg>';
  }

  get internalHidden() {
    return this.#internals.ariaHidden;
  }
}

customElements.define('deco-icon', DecoIcon);

const icon = document.createElement('deco-icon');
document.body.append(icon);
console.log(icon.internalHidden);
console.log(icon.hasAttribute('aria-hidden'));

true false

Sichtbarkeit für Hilfstechnologien dynamisch umschalten

class LoadingSpinner extends HTMLElement {
  static observedAttributes = ['active'];
  #internals = this.attachInternals();

  connectedCallback() {
    this.#update();
  }

  attributeChangedCallback() {
    this.#update();
  }

  #update() {
    const active = this.hasAttribute('active');
    // Inaktiver Spinner wird aus dem Accessibility Tree entfernt
    this.#internals.ariaHidden = active ? 'false' : 'true';
    this.#internals.role = 'status';
    this.#internals.ariaLabel = active ? 'Wird geladen…' : null;
  }
}

customElements.define('loading-spinner', LoadingSpinner);

const spinner = document.createElement('loading-spinner');
document.body.append(spinner);
spinner.setAttribute('active', '');

Attribut des Nutzers überschreibt den internen Standardwert

class HiddenByDefault extends HTMLElement {
  #internals = this.attachInternals();
  constructor() {
    super();
    this.#internals.ariaHidden = 'true';
  }
  get internals() { return this.#internals; }
}
customElements.define('hidden-default', HiddenByDefault);

const el = document.createElement('hidden-default');
// Der Nutzer macht das Element explizit wieder zugänglich
el.setAttribute('aria-hidden', 'false');
console.log(el.ariaHidden);           // Attribut-Reflection
console.log(el.internals.ariaHidden); // interner Standardwert

false true

// Wichtig · Fallstricke

Nur für autonome Custom Elements: attachInternals() wirft eine NotSupportedError-Ausnahme bei eingebauten Elementen, bei angepassten Built-ins (is="…") und beim zweiten Aufruf.
Vorrang: Ein explizit gesetztes aria-hidden-Attribut auf dem Host überschreibt den Wert aus ElementInternals. Umgekehrt spiegelt element.ariaHidden nur das Attribut wider, nicht den internen Wert.
Nicht auf fokussierbare Elemente anwenden: Setzen Sie "true" nie auf Komponenten, die interaktiv oder fokussierbar sind oder solche Nachfahren enthalten. Tastaturnutzer landen sonst auf Elementen, die Screenreader nicht ansagen. Für echtes Ausblenden eignen sich hidden oder inert besser.
Nur Zeichenketten: Setzen Sie "true" statt des Booleans true. Der Boolean wird zwar zu "true" umgewandelt, false wird aber zu "false" und nicht zu null.
Kompatibilität: Firefox unterstützt die ARIA-Reflection auf ElementInternals erst ab Version 119. Für ältere Browser prüfen Sie die Unterstützung mit 'ariaHidden' in ElementInternals.prototype und setzen ersatzweise das Attribut im connectedCallback.

Siehe auch

ElementInternals.ariaChecked ElementInternals.ariaLive ElementInternals.ariaColIndex ElementInternals.ariaCurrent ElementInternals.ariaLabel