HTMLDialogElement.returnValue — Eigenschaft · JavaScript-Referenz

Signatur

HTMLDialogElement.returnValue

Beschreibung

Die Eigenschaft returnValue ist ein String, der als „Ergebnis“ eines <dialog>-Elements dient. So lässt sich nach dem Schließen auswerten, wie der Dialog beendet wurde, etwa über „Bestätigen“, „Abbrechen“ oder eine bestimmte Auswahl.

Gesetzt wird der Wert auf drei Wegen:

durch Aufruf von dialog.close(returnValue) mit einem Argument,
automatisch beim Absenden eines Formulars mit method="dialog": Dann wird der value des auslösenden Submit-Buttons übernommen,
durch direkte Zuweisung dialog.returnValue = "...".

Typischerweise liest man den Wert im close-Event aus. Damit kann ein Dialog als einfacher, deklarativer Ersatz für confirm() oder prompt() dienen, ohne dass Formulardaten an den Server gehen.

Wichtig: Beim Öffnen per show() oder showModal() wird der Wert nicht automatisch zurückgesetzt. Wer den Dialog mehrfach verwendet, sollte returnValue vor dem Öffnen selbst auf "" setzen.

Rückgabewert

Typ

string

Beschreibung

Der aktuelle Rückgabewert des Dialogs. Anfangs ist er ein leerer String "". Nicht-String-Werte werden bei der Zuweisung in einen String umgewandelt.

Beispiele

Bestätigungsdialog mit Formular method="dialog"

// HTML:
// <dialog id="confirm">
//   <form method="dialog">
//     <p>Datei wirklich löschen?</p>
//     <button value="cancel">Abbrechen</button>
//     <button value="delete">Löschen</button>
//   </form>
// </dialog>
// <button id="open">Datei löschen</button>

const dialog = document.getElementById('confirm');

document.getElementById('open').addEventListener('click', () => {
  dialog.returnValue = ''; // alten Wert zurücksetzen
  dialog.showModal();
});

dialog.addEventListener('close', () => {
  console.log(`Ergebnis: ${dialog.returnValue}`);
  if (dialog.returnValue === 'delete') {
    // Löschvorgang starten ...
  }
});

Ergebnis: delete (nach Klick auf „Löschen“)

Wert programmatisch über close() setzen

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

// z. B. nach 5 Sekunden automatisch schließen
setTimeout(() => dialog.close('timeout'), 5000);

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

timeout

Dialog als Promise-basiertes confirm()

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

const main = async () => {
  const dialog = document.getElementById('confirm');
  const answer = await askUser(dialog);
  // Leerer String = per Escape-Taste geschlossen
  console.log(answer || 'abgebrochen (Escape)');
};

main();

abgebrochen (Escape) bzw. der value des gedrückten Buttons

// Wichtig · Fallstricke

Kein automatisches Zurücksetzen: showModal() und show() leeren returnValue nicht. Ohne manuelles Zurücksetzen bleibt der Wert der letzten Nutzung erhalten.
Escape-Taste: Schließt der Nutzer einen modalen Dialog mit Esc (bzw. über das cancel-Event), bleibt returnValue unverändert. Einen eigenen „Abbruch“-Wert setzt man am besten im cancel-Handler.
close() ohne Argument lässt den bisherigen Wert stehen und setzt ihn nicht auf "".
Ein Submit-Button ohne value-Attribut ändert returnValue nicht. Jeder Button sollte also einen eindeutigen value haben.
Der Wert ist immer ein String: Zahlen oder Objekte werden umgewandelt (close(42) ergibt "42"). Komplexe Daten liest man besser direkt aus dem Formular aus, z. B. mit FormData.
Kompatibilität: <dialog> wird seit März 2022 von allen modernen Browsern unterstützt (Safari ab 15.4, Firefox ab 98). Für ältere Browser gibt es ein Polyfill.

Siehe auch

HTMLDialogElement.open HTMLDialogElement.closedBy HTMLDataElement.value HTMLInputElement.defaultValue HTMLButtonElement.value