HTMLElement.hidden — Eigenschaft · JavaScript-Referenz

Signatur

HTMLElement.hidden

Beschreibung

Die Eigenschaft hidden spiegelt das globale HTML-Attribut hidden wider. Wird sie auf true gesetzt, fügt der Browser das Attribut hinzu. Das Element wird dann nicht angezeigt, weil das Standard-Stylesheet des Browsers [hidden] { display: none; } vorgibt. Außerdem nimmt es das Element aus dem Barrierefreiheitsbaum. Mit false wird das Attribut wieder entfernt.

Gedacht ist hidden für Inhalte, die im aktuellen Zustand nicht relevant sind, zum Beispiel noch nicht freigeschaltete Formularschritte, Fehlermeldungen vor der ersten Eingabe oder Platzhalter während eines Ladevorgangs. Wenn man Elemente per JavaScript ein- und ausblendet, ist element.hidden = true meist besser lesbar als element.style.display = "none". Die Darstellungslogik bleibt dabei im HTML/CSS, und die ursprüngliche display-Angabe geht nicht verloren.

Neuere Browser kennen zusätzlich den Wert "until-found". Ein so verstecktes Element bekommt content-visibility: hidden statt display: none. Es bleibt dann über die Suche im Browser (Strg+F) und über Textfragment-Links (#:~:text=) auffindbar. Wird es gefunden, feuert der Browser das Event beforematch, entfernt das Attribut und macht das Element sichtbar. Das passt gut zu Akkordeons und aufklappbaren FAQ-Bereichen.

Parameter

Name	Typ	Default	Beschreibung
$value	boolean \| "until-found"	false	Nur beim Setzen. `true` setzt das Attribut `hidden`, `false` entfernt es, `"until-found"` setzt `hidden="until-found"`. Andere Werte werden in einen Wahrheitswert umgewandelt (truthy bedeutet ausgeblendet).

Rückgabewert

Typ

boolean | "until-found"

Beschreibung

true, wenn das Attribut hidden vorhanden ist, sonst false. Hat das Attribut den Wert until-found, wird in unterstützenden Browsern der String "until-found" zurückgegeben.

Beispiele

Details per Button ein- und ausblenden

// HTML: <button id="toggle" aria-controls="details" aria-expanded="false">Details</button>
//       <div id="details" hidden>Weitere Informationen …</div>
const button = document.querySelector('#toggle');
const details = document.querySelector('#details');

button.addEventListener('click', () => {
  details.hidden = !details.hidden;
  button.setAttribute('aria-expanded', String(!details.hidden));
  console.log('Versteckt:', details.hidden);
});

Versteckt: false (nach dem ersten Klick) Versteckt: true (nach dem zweiten Klick)

Lade-Hinweis und Fehlermeldung beim Fetch

const loader = document.querySelector('#loader');
const error = document.querySelector('#error');
const list = document.querySelector('#list');

const loadUsers = async () => {
  loader.hidden = false;
  error.hidden = true;
  try {
    const res = await fetch('https://jsonplaceholder.typicode.com/users');
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    const users = await res.json();
    list.replaceChildren(...users.map(u => {
      const li = document.createElement('li');
      li.textContent = u.name;
      return li;
    }));
  } catch (e) {
    error.textContent = `Fehler: ${e.message}`;
    error.hidden = false;
  } finally {
    loader.hidden = true;
  }
};

loadUsers();

Attribut und Eigenschaft im Vergleich

const box = document.createElement('div');
console.log(box.hidden);                  // false

box.hidden = true;
console.log(box.outerHTML);               // <div hidden=""></div>

// Achtung: Der String "false" lässt das Attribut bestehen!
box.setAttribute('hidden', 'false');
console.log(box.hidden);                  // true

box.hidden = false;
console.log(box.hasAttribute('hidden'));  // false

false <div hidden=""></div> true false

Akkordeon mit "until-found" und beforematch

// HTML: <h3>Versand</h3><div class="panel" hidden="until-found">Wir liefern in 2–3 Tagen …</div>
document.querySelectorAll('.panel').forEach(panel => {
  panel.addEventListener('beforematch', () => {
    // Wird vor dem Aufdecken durch die Seitensuche ausgelöst
    panel.previousElementSibling?.classList.add('open');
    console.log('Panel durch Suche geöffnet');
  });
});

// Per Skript: nur setzen, wenn unterstützt
const panel = document.querySelector('.panel');
if ('onbeforematch' in document.body) {
  panel.hidden = 'until-found';
} else {
  panel.hidden = true; // Rückfall für ältere Browser
}

Panel durch Suche geöffnet (nach Treffer über Strg+F)

// Wichtig · Fallstricke

CSS überschreibt hidden: Das Ausblenden kommt nur aus dem Standard-Stylesheet des Browsers. Jede eigene display-Regel wie .card { display: flex; } ist stärker, und das Element bleibt trotz hidden sichtbar. Abhilfe schafft eine globale Regel: [hidden] { display: none !important; }.
Boolesches Attribut: Allein die Anwesenheit des Attributs zählt. setAttribute('hidden', 'false') blendet das Element trotzdem aus. Zum Einblenden el.hidden = false oder removeAttribute('hidden') verwenden.
Barrierefreiheit: Ausgeblendete Elemente sind auch für Screenreader unsichtbar. Auf ausgeblendete Inhalte darf aria-describedby bzw. aria-labelledby zwar verweisen, für visuell verborgene, aber vorlesbare Inhalte eignet sich jedoch eher eine „visually-hidden“-CSS-Klasse.
Keine Sicherheitsfunktion: Versteckter Inhalt steht weiterhin im DOM und im Quelltext. Vertrauliche Daten nie nur per hidden „verbergen“.
Nicht für Präsentationsvarianten: Um Inhalte je nach Layout auszublenden (etwa auf Mobilgeräten), sind CSS-Media-Queries passender. hidden bedeutet semantisch „derzeit nicht relevant“.
Kompatibilität: true/false funktionieren in allen Browsern. "until-found" und das Event beforematch gibt es seit Chromium 102; in Firefox und Safari erst in neueren Versionen. Vor der Nutzung per Feature-Test prüfen, z. B. mit 'onbeforematch' in document.body.

Siehe auch

HTMLElement.style Element.setAttribute() Element.removeAttribute() Element.toggleAttribute() HTMLElement.inert HTMLElement