Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / HTML

dialog — a native dialog box

The `dialog` element represents a temporary window for completing a task or presenting information. Its `show()` method displays it non-modally, while `showModal()` blocks interaction with the rest of the document.

Version: WHATWG HTML Living Standard; index snapshot date recorded separately

Syntax

<dialog>…</dialog>
dialog.show();
dialog.showModal();
dialog.close(result);

dialog is a window for a brief application interaction, not a substitute for a menu or tooltip. Both start and end tags are required. Without open, it is not shown by default; open alone does not create a modal dialog.

show() displays a non-modal dialog. showModal() places it in the top layer; the rest of the document becomes inactive (inert). The element must be connected to the document. Calling showModal() on a dialog already open non-modally throws InvalidStateError.

Provide a meaningful name, for example through aria-labelledby, and a visible close button. Choose initial focus using autofocus on a suitable control. Do not set tabindex on dialog.

close(result) closes the dialog, stores the supplied string in returnValue, and causes a close event. requestClose(result) first fires cancelable cancel; preventDefault() can stop closure. Do not manually remove open, because that bypasses the proper closing lifecycle. closedby controls automatic closing: any also allows outside clicks, closerequest allows close requests, and none allows neither. Without this attribute, modal dialogs handle close requests and non-modal dialogs do not.

Examples

<!doctype html>
<html lang="en">
<meta charset="utf-8">
<title>Dialog example</title>
<button id="launch" type="button">Open</button>
<dialog id="box" aria-labelledby="heading">
  <h2 id="heading">Confirmation</h2>
  <p>Close this dialog to continue.</p>
  <button id="finish" type="button" autofocus>OK</button>
</dialog>
<p id="status" role="status">Ready</p>
<script>
  const box = document.getElementById('box');
  const status = document.getElementById('status');
  document.getElementById('launch').addEventListener('click', () => {
    box.returnValue = '';
    box.showModal();
  });
  document.getElementById('finish').addEventListener('click', () => {
    box.close('confirmed');
  });
  box.addEventListener('close', () => {
    status.textContent = box.returnValue === 'confirmed'
      ? 'Result: confirmed'
      : 'Result: dismissed';
  });
</script>
</html>

Result

Result: confirmed

The displayed code and declared result were verified in an isolated environment using the method recorded in the verification evidence for this exact version.

Sources