HTMLDialogElement.show() — Methode · JavaScript-Referenz

Signatur

HTMLDialogElement.prototype.show()

Beschreibung

show() öffnet ein <dialog>-Element als nicht-modalen Dialog und setzt dabei das Attribut open. Anders als bei showModal() wird die restliche Seite nicht blockiert: Nutzer können weiter scrollen, klicken und Formulare ausfüllen, während der Dialog sichtbar ist.

Nicht-modale Dialoge eignen sich für Inhalte, die neben der eigentlichen Arbeit stehen, zum Beispiel:

Hinweis- oder Info-Panels, Hilfetexte und Tipps
schwebende Werkzeugleisten oder Such-und-Ersetzen-Fenster
Chat- oder Benachrichtigungsfenster, die offen bleiben dürfen

Der Dialog wird nicht in den Top Layer verschoben. Es gibt also kein ::backdrop-Pseudoelement, die Seite wird nicht inert, und die Position im Stapel richtet sich wie gewohnt nach z-index und dem Stapelkontext. Beim Öffnen setzt der Browser den Fokus auf das erste Element mit autofocus oder auf das erste fokussierbare Element im Dialog. Geschlossen wird der Dialog mit close() oder über ein Formular mit method="dialog".

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Als Nebeneffekt wird das Attribut open gesetzt, und die Eigenschaft dialog.open liefert danach true.

Beispiele

Info-Panel öffnen und schließen

// HTML:
// <button id="info">Info</button>
// <dialog id="panel"><p>Hinweis: Änderungen werden automatisch gespeichert.</p>
//   <button id="zu">Schließen</button></dialog>

const dialog = document.querySelector('#panel');

document.querySelector('#info').addEventListener('click', () => {
  dialog.show();
  console.log('offen:', dialog.open);
});

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

offen: true offen: false

Nicht-modalen Dialog per Button umschalten

const hilfe = document.querySelector('#hilfe-dialog');
const toggle = document.querySelector('#hilfe-toggle');

toggle.addEventListener('click', () => {
  if (hilfe.open) {
    hilfe.close();
  } else {
    hilfe.show(); // Seite bleibt bedienbar
  }
  toggle.setAttribute('aria-expanded', String(hilfe.open));
});

Formular mit method="dialog" und returnValue auswerten

// HTML:
// <dialog id="suche">
//   <form method="dialog">
//     <input name="q" autofocus>
//     <button value="abbrechen">Abbrechen</button>
//     <button value="suchen">Suchen</button>
//   </form>
// </dialog>

const suche = document.querySelector('#suche');

suche.addEventListener('close', () => {
  console.log('Aktion:', suche.returnValue);
});

suche.returnValue = '';
suche.show(); // Fokus springt ins Feld mit autofocus

Aktion: suchen (nach Klick auf „Suchen“)

InvalidStateError bei bereits modal geöffnetem Dialog abfangen

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

try {
  dlg.show();
} catch (err) {
  console.log(err.name);
}

InvalidStateError

// Wichtig · Fallstricke

Ausnahmen: show() wirft eine InvalidStateError-DOMException, wenn der Dialog bereits modal geöffnet ist oder als Popover (popover-Attribut) gerade angezeigt wird. Ist er schon nicht-modal offen, bewirkt ein weiterer Aufruf nichts.
Kein Schließen mit Escape: Nicht-modale Dialoge reagieren standardmäßig nicht auf die Escape-Taste, und es gibt kein cancel-Ereignis. Wer das möchte, muss es selbst umsetzen (z. B. mit einem keydown-Listener) oder das neuere Attribut closedby verwenden. Dieses wird noch nicht von allen Browsern unterstützt.
Kein Top Layer, kein Backdrop: ::backdrop gilt nur für showModal(). Nicht-modale Dialoge können von anderen Elementen verdeckt werden, deshalb auf z-index und position achten.
Attribut open nicht direkt setzen: Wer open von Hand setzt oder entfernt, umgeht die Fokus-Logik und das close-Ereignis. Besser show() und close() verwenden.
Barrierefreiheit: Weil der Fokus nicht im Dialog festgehalten wird, sollte das auslösende Element den Zustand mitteilen (z. B. mit aria-expanded). Nach dem Schließen setzt der Browser den Fokus auf das zuvor fokussierte Element zurück.
Kompatibilität: In allen aktuellen Browsern verfügbar (Baseline seit 2022). Für sehr alte Safari- und Firefox-Versionen gibt es den Polyfill dialog-polyfill.

Siehe auch

HTMLDialogElement.close() HTMLDialogElement.showModal() HTMLDialogElement.requestClose() HTMLMediaElement.load() HTMLMediaElement.play()