HTMLDetailsElement — Schnittstelle · JavaScript-Referenz

Signatur

interface HTMLDetailsElement extends HTMLElement

Beschreibung

HTMLDetailsElement ist die DOM-Schnittstelle für das HTML-Element <details>. Sie erbt alle Eigenschaften und Methoden von HTMLElement, Element, Node und EventTarget und ergänzt sie um zwei eigene Eigenschaften: open (boolean) gibt an, ob der Inhalt gerade sichtbar ist, und name (string) fasst mehrere <details>-Elemente zu einer Gruppe zusammen, in der immer nur eines offen sein kann – so entsteht ein Akkordeon.

Die Schnittstelle eignet sich für FAQ-Listen, aufklappbare Einstellungsbereiche, Akkordeons oder „Mehr anzeigen“-Abschnitte. Der Browser liefert ohne JavaScript bereits Tastaturbedienung, Fokussierbarkeit über <summary> und die passende Semantik für Screenreader. JavaScript braucht man nur, wenn der Zustand gespeichert, gemeinsam für alle Elemente gesteuert oder auf Änderungen reagiert werden soll.

Bei jeder Änderung des Zustands – ob durch Benutzerklick oder durch Setzen von open – löst das Element das Ereignis toggle aus. Es wird asynchron ausgelöst und bei schnell aufeinanderfolgenden Wechseln zusammengefasst. Neuere Browser stellen im ToggleEvent zusätzlich oldState und newState ("open"/"closed") bereit.

Parameter

Name	Typ	Default	Beschreibung
$open	boolean	false	Eigenschaft, die das HTML-Attribut `open` widerspiegelt. `true` klappt den Inhalt auf, `false` klappt ihn zu.
$name	string	""	Eigenschaft, die das HTML-Attribut `name` widerspiegelt. Elemente mit gleichem `name` bilden eine exklusive Gruppe: Öffnet man eines, schließen sich die anderen automatisch.

Beispiele

Details-Element per Skript erzeugen

const details = document.createElement('details');
const summary = document.createElement('summary');
summary.textContent = 'Versandkosten';
details.append(summary, 'Ab 50 € Bestellwert liefern wir versandkostenfrei.');
details.open = true; // direkt aufgeklappt anzeigen
document.body.append(details);

console.log(details instanceof HTMLDetailsElement);
console.log(details.open);

true true

Alle FAQ-Einträge auf- oder zuklappen

// HTML: <button id="alle">Alle öffnen</button> + mehrere <details class="faq">
const button = document.querySelector('#alle');
const eintraege = document.querySelectorAll('details.faq');

button.addEventListener('click', () => {
  const allesOffen = [...eintraege].every((d) => d.open);
  eintraege.forEach((d) => { d.open = !allesOffen; });
  button.textContent = allesOffen ? 'Alle öffnen' : 'Alle schließen';
});

Zustand mit dem toggle-Ereignis im localStorage speichern

const details = document.querySelector('#erweitert');

// gespeicherten Zustand wiederherstellen
details.open = localStorage.getItem('erweitert-offen') === 'true';

details.addEventListener('toggle', (event) => {
  localStorage.setItem('erweitert-offen', String(details.open));
  console.log(`Neuer Zustand: ${event.newState ?? (details.open ? 'open' : 'closed')}`);
});

Neuer Zustand: open

Exklusives Akkordeon über die name-Eigenschaft

const gruppe = ['Konto', 'Datenschutz', 'Benachrichtigungen'].map((titel) => {
  const d = document.createElement('details');
  d.name = 'einstellungen'; // gleiche Gruppe
  d.innerHTML = `<summary>${titel}</summary><p>Optionen für ${titel}</p>`;
  document.body.append(d);
  return d;
});

gruppe[0].open = true;
gruppe[1].open = true; // schließt gruppe[0] automatisch
console.log(gruppe.map((d) => d.open));

[false, true, false]

// Wichtig · Fallstricke

Das Ereignis toggle bubbelt nicht. Für Ereignisdelegation am Elternelement muss man addEventListener('toggle', handler, true) (Capture-Phase) verwenden.
toggle wird asynchron ausgelöst. Wer open setzt und direkt danach Code ausführt, kann sich nicht darauf verlassen, dass der Handler bereits gelaufen ist.
Die Eigenschaft name (exklusive Akkordeons) wird erst seit 2024 unterstützt (Chrome 120, Safari 17.2, Firefox 130). Ältere Browser ignorieren sie; dann braucht man einen eigenen toggle-Handler, der die anderen Elemente schließt. Auch newState/oldState am ToggleEvent gibt es noch nicht überall – deshalb im Zweifel details.open auslesen.
Fehlt ein <summary>-Kindelement, zeigt der Browser eine eigene Beschriftung an (z. B. „Details“). Für Barrierefreiheit immer ein aussagekräftiges <summary> angeben.
Das Suchen im Browser (Strg+F) klappt geschlossene <details> in modernen Chromium-Browsern automatisch auf, wenn ein Treffer darin liegt – dabei wird ebenfalls toggle ausgelöst.
Bei innerHTML mit Benutzereingaben (siehe Akkordeon-Beispiel) droht XSS; für fremde Daten lieber textContent verwenden.

Siehe auch

HTMLDataElement HTMLDataListElement HTMLMetaElement HTMLTableElement HTMLDListElement