HTMLDialogElement.closedBy — Eigenschaft · JavaScript-Referenz

Signatur

HTMLDialogElement.closedBy

Beschreibung

Die Eigenschaft closedBy spiegelt das HTML-Attribut closedby eines <dialog>-Elements wider. Sie legt fest, auf welche Arten ein Nutzer den Dialog schließen kann, ohne dass du eigenen JavaScript-Code für Tastatur- oder Klick-Behandlung schreiben musst. Mögliche Werte sind:

"any": Der Dialog lässt sich durch Light Dismiss (Klick bzw. Tippen außerhalb des Dialogs), durch eine Schließanforderung (z. B. Esc, Zurück-Geste unter Android) und durch Entwickler-Mechanismen schließen.
"closerequest": Schließen per Schließanforderung (Esc) und per Entwickler-Mechanismen, aber nicht per Klick außerhalb.
"none": Nur Entwickler-Mechanismen schließen den Dialog, also close(), requestClose() oder ein Formular mit method="dialog".

Ist das Attribut nicht gesetzt oder ungültig, gilt ein automatischer Zustand: Mit showModal() geöffnete Dialoge verhalten sich wie "closerequest", mit show() geöffnete (nicht-modale) Dialoge wie "none". Der Getter liefert immer das tatsächlich wirksame Schlüsselwort, also nie einen leeren String.

Typische Einsatzfälle sind Menüs, Info-Popups oder Bildvorschauen, die sich per Klick auf den Hintergrund schließen sollen ("any"), sowie kritische Bestätigungsdialoge, die der Nutzer bewusst über einen Button beantworten muss ("none").

Parameter

Name	Typ	Default	Beschreibung
$value	"any" \| "closerequest" \| "none"	automatisch: "closerequest" (modal) bzw. "none" (nicht-modal)	Beim Setzen: gewünschtes Schließverhalten. Wird als Attribut `closedby` ins DOM geschrieben. Ungültige Werte führen zum automatischen Verhalten.

Rückgabewert

Typ

string

Beschreibung

Das wirksame Schließverhalten: "any", "closerequest" oder "none".

Beispiele

Light Dismiss für ein modales Menü aktivieren

// HTML: <dialog id="menu"><p>Menü-Inhalt</p></dialog> <button id="open">Menü</button>
const dialog = document.querySelector('#menu');
dialog.closedBy = 'any'; // Klick außerhalb oder Esc schließt

document.querySelector('#open').addEventListener('click', () => {
  dialog.showModal();
});

dialog.addEventListener('close', () => {
  console.log('Menü geschlossen, closedBy =', dialog.closedBy);
});

Menü geschlossen, closedBy = any

Wirksamen Standardwert auslesen

const dialog = document.createElement('dialog');
document.body.append(dialog);

dialog.show();
console.log(dialog.closedBy); // nicht-modal ohne Attribut
dialog.close();

dialog.showModal();
console.log(dialog.closedBy); // modal ohne Attribut
dialog.close();

dialog.setAttribute('closedby', 'any');
console.log(dialog.closedBy);

none closerequest any

Bestätigungsdialog, der nur per Button schließt – mit Fallback

// HTML:
// <dialog id="confirm">
//   <form method="dialog">
//     <p>Konto wirklich löschen?</p>
//     <button value="cancel">Abbrechen</button>
//     <button value="ok">Löschen</button>
//   </form>
// </dialog>
const confirmDialog = document.querySelector('#confirm');

if ('closedBy' in HTMLDialogElement.prototype) {
  confirmDialog.closedBy = 'none';
} else {
  // Fallback: Esc manuell unterdrücken
  confirmDialog.addEventListener('cancel', (event) => event.preventDefault());
}

const askUser = () => new Promise((resolve) => {
  confirmDialog.addEventListener('close', () => resolve(confirmDialog.returnValue), { once: true });
  confirmDialog.showModal();
});

const answer = await askUser();
console.log('Antwort:', answer);

Antwort: ok

// Wichtig · Fallstricke

Browser-Unterstützung: Verfügbar ab Chrome/Edge 134 und Firefox 141; Safari unterstützt die Eigenschaft (Stand 2025) noch nicht. Prüfe mit 'closedBy' in HTMLDialogElement.prototype und rüste Light Dismiss notfalls per Klick-Listener auf dem Dialog nach (Klickkoordinaten mit getBoundingClientRect() vergleichen).
Auch bei "none" kann der Browser eine Schließanforderung in Ausnahmefällen durchsetzen, etwa wenn der Nutzer wiederholt Esc drückt, ohne vorher mit der Seite interagiert zu haben (Schutz vor Missbrauch). Verlasse dich also nicht darauf, dass sich ein Dialog nie schließen lässt.
Bei nicht-modalen Dialogen (show()) wirkt "any" ebenfalls, der Standard ist dort aber "none". Esc schließt einen nicht-modalen Dialog nur, wenn du closedby ausdrücklich setzt.
Beim Schließen per Light Dismiss oder Esc wird zuerst das Ereignis cancel und danach close ausgelöst; returnValue bleibt dabei unverändert.
Ungültige Werte (z. B. Tippfehler wie "close-request") werden stillschweigend ignoriert, dann gilt das automatische Verhalten.

Siehe auch

HTMLDialogElement.open HTMLDialogElement.returnValue HTMLAreaElement.coords HTMLMediaElement.paused HTMLMediaElement.played