HTML <dialog> Tag

Beginner
6 min read
Updated: Oct 2026
4 examples
Live preview

Definition and Usage

The <dialog> element represents a modal or non-modal dialog box — for example a confirm message or a small panel. Modal dialogs block the rest of the page; non-modal ones do not.

Prefer JavaScript showModal() / show() / close() to open and close. Always include a clear close control (button or <form method="dialog">). Style the modal dimming layer with ::backdrop.

Baseline · Widely available.

Core <dialog> has been widely available since about March 2022. Some extras (such as closedby) have newer or uneven support — test if you rely on them.

Do not use tabindex on <dialog>.

The dialog itself is not meant to take a tabindex. Focus interactive content inside it (MDN). Prefer autofocus on the control users should hit first (often Close).

Prefer methods over toggling open.

Setting the open attribute alone creates a non-modal dialog. For modals, use showModal().

HTML Syntax

syntax.html
<dialog> …content… </dialog>

Both start and end tags are required. Put headings, text, buttons, or a form inside. Without being opened (via method or open), the dialog is not shown to users.

Attributes

Attributes specific to <dialog> (plus globals):

AttributeDescriptionTry it
openWhen present, the dialog is open and non-modal. Prefer show() / showModal() in most appsTry it
closedbyControls how users may dismiss the dialog (any, closerequest, none). Newer — support variesSee edge cases

Global Attributes

The <dialog> tag also supports the Global Attributes in HTML (except do not add tabindex on the dialog itself).

Live Preview

Open a modal dialog with showModal(), then close it with the button or Esc.

Uses a real <dialog>. Modal adds a backdrop and inert page content.

Page content

Click Open dialog above. This paragraph stays behind a modal backdrop.

Ready — mode: modal (showModal)

Sample dialog

Greetings — this is a native HTML dialog.

HTML Examples

Short, copy-ready snippets. Use Try It Yourself for a live editor. Modal demos need a tiny bit of JavaScript for showModal().

Example 1 — Modal with showModal()

Open a blocking dialog; close with a button (or Esc).

HTML
<button type="button" id="open">Show dialog</button>

<dialog id="box">
  <p>Save your changes before leaving?</p>
  <button type="button" id="close" autofocus>Close</button>
</dialog>

<script>
  const box = document.getElementById("box");
  document.getElementById("open").onclick = () => box.showModal();
  document.getElementById("close").onclick = () => box.close();
</script>
Try It Yourself

How It Works

  1. Write a <dialog> with a message and a close control.
  2. Call showModal() from a button click to open it as modal.
  3. Call close() (or press Esc) to dismiss.
  4. Put autofocus on the close button when that is the first action.

Example 2 — open + method="dialog"

HTML-only non-modal dialog that starts open and closes on form submit.

HTML
<dialog open>
  <p>Greetings, one and all!</p>
  <form method="dialog">
    <button>OK</button>
  </form>
</dialog>
Try It Yourself

How It Works

  1. Add open so the dialog starts visible (non-modal).
  2. Nest <form method="dialog"> with a submit button.
  3. Submit the form — the dialog closes; no page navigation.
  4. For reopenable UIs, prefer show() / showModal() instead of only open.

Example 3 — Non-Modal with show()

Open a dialog that does not block the rest of the page.

HTML
<button type="button" id="open2">Open tip</button>
<p>You can still select this text while the tip is open.</p>

<dialog id="tip">
  <p>Tip: Save often.</p>
  <form method="dialog">
    <button autofocus>Got it</button>
  </form>
</dialog>

<script>
  const tip = document.getElementById("tip");
  document.getElementById("open2").onclick = () => tip.show();
</script>
Try It Yourself

How It Works

  1. Call show() instead of showModal().
  2. No inert backdrop — the page stays usable.
  3. Close with method="dialog" or close().
  4. Esc does not close non-modal dialogs by default — keep a visible close control.

Example 4 — <dialog> vs <details>

Use dialog for overlays; use details for inline expand/collapse.

HTML
<!-- Overlay / focused task -->
<button type="button" id="ask">Confirm</button>
<dialog id="confirm">
  <p>Delete this file?</p>
  <form method="dialog">
    <button value="cancel">Cancel</button>
    <button value="ok" autofocus>Delete</button>
  </form>
</dialog>

<!-- Inline disclosure -->
<details>
  <summary>More about deletion</summary>
  <p>Deleted files go to the trash for 30 days.</p>
</details>

<script>
  const confirmDlg = document.getElementById("confirm");
  document.getElementById("ask").onclick = () => confirmDlg.showModal();
</script>
Try It Yourself

How It Works

  1. Dialog: focused task with optional modal backdrop.
  2. Details: inline expand in the document flow (no modal).
  3. Pick by UX. Confirm/alert → dialog; FAQ tip in place → <details>.
  4. Always offer a close path on dialogs (button or Esc for modals).

Edge Cases & Pitfalls

Most issues are missing close controls, wrong open method, or fighting native focus rules.

a11y

Always provide a close control

Not every device has Esc. Include Cancel/Close/OK that users can activate.

api

Modal vs non-modal API

showModal() for blocking UI; show() or open for non-modal. Do not assume open alone is modal.

focus

No tabindex on dialog

Focus contents instead. Use autofocus on the primary control when helpful.

css

Style the backdrop separately

Modal backdrops use ::backdrop. Closed dialogs stay in the DOM but are not displayed.

newer

closedby support varies

This attribute fine-tunes dismiss gestures. Treat it as progressive enhancement until your audience supports it.

Browser Support

The <dialog> element is standard HTML. Core support is widely available; some related attributes are newer.

✓ Baseline · Widely available*

<dialog>

Widely available since about March 2022. Chrome, Firefox, Safari, and Edge support showModal/show/close. Features like closedby and invoker commands need newer browsers.

94% Global support (approx.)
Google Chrome 37+
Full support
Mozilla Firefox 98+
Full support
Apple Safari 15.4+
Full support
Microsoft Edge 79+
Full support
Opera 24+
Full support
Samsung Internet All
Full support
Internet Explorer No
Not supported
<dialog> Widely supported

Bottom line: Safe for modern sites. Prefer showModal/show/close and a visible close button; enhance with closedby only after checking support.

Key Takeaways

  • Role: native dialog box — modal with showModal(), non-modal with show().
  • Close: button + close(), Esc (modal), or <form method="dialog">.
  • Focus: no tabindex on dialog; use autofocus inside when helpful.
  • Style: ::backdrop for the modal dim layer behind the dialog.

One line: use <dialog> with showModal() for focused tasks — and always give users a clear way out.

Default CSS Settings

Closed dialogs are not displayed. Open dialogs are centered by the UA stylesheet (simplified):

default.css
dialog {
  display: block; /* when open; closed dialogs are not shown */
  position: fixed;
  inset: 0;
  margin: auto;
  border: solid;
  padding: 1em;
  max-width: calc(100% - 2em);
  max-height: calc(100% - 2em);
}

dialog::backdrop {
  background: rgba(0, 0, 0, 0.1);
}

Exact UA rules vary. Keep study CSS minimal; customize padding, border, and ::backdrop as needed.

Frequently Asked Questions

The dialog element creates a modal or non-modal dialog box — for alerts, confirmations, or small panels. Modal dialogs block the rest of the page; non-modal ones do not.
Call dialog.showModal() from JavaScript. Prefer that over setting the open attribute. Modal dialogs get a backdrop and can be closed with Esc by default.
Call dialog.show(), or (less preferred) add the open attribute. Non-modal dialogs allow interaction with the rest of the page.
Put a form inside the dialog with method="dialog" and a submit button. Submitting that form closes the dialog.
No. Do not use tabindex on the dialog element. Focus its interactive contents (for example a close button with autofocus).
No. details is an inline disclosure in the page flow. dialog is a dialog box that can be modal with a backdrop and focus management.

Next: dir

Learn about the obsolete dir element and modern list alternatives.

dir tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

15 people found this page helpful