HTMLDialogElement.close() — Methode · JavaScript-Referenz

Signatur

HTMLDialogElement.prototype.close(returnValue)

Beschreibung

Die Methode close() schließt ein <dialog>-Element, das vorher mit show() oder showModal() geöffnet wurde. Dabei entfernt der Browser das Attribut open. Bei modalen Dialogen wird zusätzlich das Element aus dem Top Layer genommen, das ::backdrop verschwindet und die Seite dahinter lässt sich wieder bedienen.

Über den optionalen Parameter returnValue gibst du an, wie der Dialog geschlossen wurde, etwa "ok", "abbrechen" oder eine ausgewählte Option. Den Wert kannst du danach über die Eigenschaft dialog.returnValue auslesen, typischerweise in einem Handler für das Event close. Das Event feuert asynchron, nachdem der Dialog geschlossen ist.

Nach dem Schließen setzt der Browser den Fokus in der Regel auf das Element zurück, das vor dem Öffnen fokussiert war. Ist der Dialog bereits geschlossen, macht der Aufruf nichts: Es gibt keinen Fehler und es wird kein close-Event ausgelöst.

Einen Dialog kannst du auch deklarativ schließen, und zwar mit einem Formular mit method="dialog". Dann wird der value des Absende-Buttons automatisch zum returnValue. Die Taste Esc schließt nur modale Dialoge und löst dabei vorher das Event cancel aus.

Parameter

Name	Typ	Default	Beschreibung
$returnValue	string		Optionaler Text, der in `dialog.returnValue` gespeichert wird. Andere Werte werden in einen String umgewandelt. Lässt du den Parameter weg, behält `returnValue` seinen bisherigen Wert.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Modalen Dialog öffnen und per Button schließen

// HTML: <dialog id="info"><p>Gespeichert!</p><button id="ok">OK</button></dialog>
const dialog = document.querySelector('#info');

dialog.showModal();

document.querySelector('#ok').addEventListener('click', () => {
  dialog.close();
  console.log('offen?', dialog.open);
});

offen? false

Bestätigungsdialog mit returnValue als Promise

// HTML: <dialog id="confirm"><p>Wirklich löschen?</p>
//   <button data-value="ja">Ja</button><button data-value="nein">Nein</button></dialog>
const confirmDialog = document.querySelector('#confirm');

confirmDialog.querySelectorAll('button').forEach((btn) => {
  btn.addEventListener('click', () => confirmDialog.close(btn.dataset.value));
});

const askConfirm = () => new Promise((resolve) => {
  confirmDialog.returnValue = ''; // alten Wert zurücksetzen
  confirmDialog.addEventListener('close', () => {
    resolve(confirmDialog.returnValue === 'ja');
  }, { once: true });
  confirmDialog.showModal();
});

const run = async () => {
  const ok = await askConfirm();
  console.log(ok ? 'Wird gelöscht' : 'Abgebrochen');
};
run();

Wird gelöscht // nach Klick auf „Ja“

Schließen per Klick auf den Hintergrund (Backdrop)

const dialog = document.querySelector('dialog');
dialog.showModal();

dialog.addEventListener('click', (event) => {
  // Klicks auf das ::backdrop haben das dialog-Element selbst als Ziel
  const rect = dialog.getBoundingClientRect();
  const inside = event.clientX >= rect.left && event.clientX <= rect.right &&
                 event.clientY >= rect.top && event.clientY <= rect.bottom;
  if (!inside) dialog.close('backdrop');
});

dialog.addEventListener('close', () => {
  console.log('Geschlossen durch:', dialog.returnValue);
});

Geschlossen durch: backdrop

// Wichtig · Fallstricke

returnValue bleibt erhalten: Rufst du close() ohne Argument auf, bleibt der alte returnValue stehen. Setze ihn vor jedem erneuten Öffnen auf '' zurück, sonst liest du veraltete Werte aus.
Das close-Event ist asynchron: Es feuert erst, nachdem close() fertig ist, und nur, wenn der Dialog vorher offen war. Code direkt nach close() läuft also vor den Handlern des Events.
cancel gibt es nur bei Esc: Ein programmatisches close() löst kein cancel-Event aus. Du kannst es also nicht mit preventDefault() verhindern.
Nicht einfach open entfernen: dialog.removeAttribute('open') blendet den Dialog zwar aus, lässt aber einen modalen Dialog im Top Layer. Außerdem feuert dann kein close-Event. Nimm immer close().
Alternative requestClose(): Die neuere Methode requestClose() löst vorher cancel aus und lässt sich dadurch abbrechen. Sie wird noch nicht überall unterstützt.
Browser-Unterstützung: <dialog> wird in allen aktuellen Browsern unterstützt (Chrome 37+, Firefox 98+, Safari 15.4+). Für ältere Browser gibt es das Polyfill dialog-polyfill.

Siehe auch

HTMLDialogElement.show() HTMLDialogElement.requestClose() HTMLDialogElement.showModal() HTMLMediaElement.load() HTMLMediaElement.pause()