Element.ariaHidden — Eigenschaft · JavaScript-Referenz

Signatur

Element.ariaHidden

Beschreibung

Die Eigenschaft ariaHidden spiegelt das ARIA-Attribut aria-hidden direkt als String wider. Wird sie gesetzt, ändert sich das Attribut im DOM – und umgekehrt. Damit lässt sich per JavaScript steuern, ob ein Element samt allen Nachfahren aus dem Barrierefreiheitsbaum entfernt wird, ohne setAttribute()/getAttribute() verwenden zu müssen.

Gültige Werte sind "true" (Element ist für assistive Technologien verborgen), "false" (Element ist sichtbar) und "undefined" (Standard, vom Browser bestimmt). Ist das Attribut nicht vorhanden, liefert die Eigenschaft null. Wird null zugewiesen, wird das Attribut entfernt.

Typische Einsatzfälle: rein dekorative Icons oder Grafiken vor Screenreadern verbergen, doppelte Inhalte (z. B. sichtbarer Text neben einem Icon mit gleichem Inhalt) ausblenden oder beim Öffnen eines modalen Dialogs den Hintergrundinhalt verstecken. aria-hidden verändert nicht die visuelle Darstellung – das Element bleibt auf dem Bildschirm sichtbar und ggf. fokussierbar.

Parameter

Name	Typ	Default	Beschreibung
$value	string \| null	null	Beim Setzen: `"true"`, `"false"` oder `"undefined"`. `null` entfernt das Attribut `aria-hidden`.

Rückgabewert

Typ

string | null

Beschreibung

Der aktuelle Wert des aria-hidden-Attributs als String ("true", "false", "undefined") oder null, wenn das Attribut nicht gesetzt ist.

Beispiele

Wert lesen und ändern

// <span id="icon" aria-hidden="true">★</span>
const icon = document.getElementById('icon');

console.log(icon.ariaHidden); // "true"

icon.ariaHidden = 'false';
console.log(icon.getAttribute('aria-hidden')); // "false"

// Attribut vollständig entfernen
icon.ariaHidden = null;
console.log(icon.hasAttribute('aria-hidden')); // false

true false false

Dekorative Icons automatisch verbergen

// Alle SVG-Icons in Buttons mit sichtbarem Text vor Screenreadern verstecken
document.querySelectorAll('button svg.icon').forEach((svg) => {
  svg.ariaHidden = 'true';
  svg.setAttribute('focusable', 'false');
});

Hintergrund bei geöffnetem Modal verbergen

const main = document.querySelector('main');
const dialog = document.querySelector('#dialog');

const openModal = () => {
  main.ariaHidden = 'true';
  main.inert = true; // verhindert zusätzlich Fokus und Klicks
  dialog.hidden = false;
  dialog.querySelector('button')?.focus();
};

const closeModal = () => {
  main.ariaHidden = null;
  main.inert = false;
  dialog.hidden = true;
};

document.querySelector('#open').addEventListener('click', openModal);
dialog.querySelector('.close').addEventListener('click', closeModal);

// Wichtig · Fallstricke

Kein Boolean: Die Eigenschaft ist ein String. el.ariaHidden = false wird zu "false" umgewandelt, el.ariaHidden = true zu "true". Beim Lesen daher per === 'true' vergleichen, nie auf Wahrheitswert prüfen – "false" ist truthy.
Fokussierbare Elemente nie verbergen: aria-hidden="true" auf Links, Buttons oder Eingabefeldern (bzw. deren Vorfahren) führt dazu, dass Tastaturnutzer auf „unsichtbare“ Elemente fokussieren. Nutze stattdessen inert, hidden oder tabindex="-1".
aria-hidden="false" macht Nachfahren eines verborgenen Elements nicht wieder sichtbar; es wirkt nicht gegen display: none oder das hidden-Attribut.
Nicht auf <body> anwenden – dadurch wird die gesamte Seite für Screenreader unzugänglich.
Kompatibilität: Die ARIA-Reflexionseigenschaften werden in Firefox erst ab Version 119 unterstützt. Für ältere Browser setAttribute('aria-hidden', 'true') verwenden – funktioniert überall.

Siehe auch

Element.role Element.ariaCurrent Element.ariaLive Element.ariaChecked Element.ariaColIndex