Back to HTML

The dialog Element for Modals

Coding Tutorials Team 18 June 2026

A correctly built modal traps focus inside itself, closes on the escape key, returns focus to whatever opened it, hides the rest of the page from assistive technology, and prevents the background scrolling. Almost every hand built modal gets at least one of these wrong. The dialog element provides all of them.

The markup

<dialog id="confirm"> <h2>Delete this article?</h2> <p>This cannot be undone.</p> <form method="dialog"> <button value="cancel">Cancel</button> <button value="delete">Delete</button> </form> </dialog>

A dialog is hidden by default and does not need to be hidden in CSS. It is opened from JavaScript, and there is no HTML-only way to open one.

showModal and show are different

The showModal method opens it as a true modal: focus is trapped inside, the rest of the page becomes inert, the escape key closes it, and a backdrop appears behind it.

The show method opens it as a non-modal dialog. It appears, and the page behind remains fully interactive. This suits something like a persistent settings panel and is not what most people mean by a modal.

Using the open attribute in the markup to display one is a third option and a mistake for modals, because it shows the dialog without any of the modal behaviour. It looks correct and traps nothing.

The form method

A form with a method of dialog closes the dialog when submitted, without sending anything anywhere. The value of the button that was pressed becomes the dialog's return value, which the opening code can read.

This is a neat way to handle a confirmation without any event listeners on the buttons themselves, and it keeps the markup declarative.

The backdrop

The area behind a modal dialog is a pseudo-element that can be styled directly.

dialog::backdrop { background: rgb(0 0 0 / 0.5); }

Clicking the backdrop does not close the dialog by default. Implementing that requires a small amount of scripting, and it is worth being careful about, since a click that lands on the backdrop after starting inside the dialog should not close it.

Focus management

When a modal opens, focus moves into it automatically. The element that receives focus is the first focusable one, unless something inside carries the autofocus attribute, which is the usual way to direct it deliberately.

For a destructive confirmation, focusing the cancel button rather than the confirm button is the safer default, since someone pressing enter reflexively should not delete anything.

When the dialog closes, focus returns to whatever had it before. This is one of the parts hand built modals most often miss, and its absence leaves keyboard users stranded at the top of the document.

Closing it

The close method closes a dialog from script and optionally sets a return value. A close event fires afterwards, which is where any cleanup belongs, such as restoring background scrolling or clearing a form inside the dialog.

Because the escape key closes a modal automatically, that cleanup must live in the close event rather than in a button handler, or pressing escape will bypass it entirely. This is the most common bug introduced when converting a hand built modal to the native element.

What it does not do

The element does not prevent the page behind from scrolling. That still needs a CSS change on the body while the dialog is open, and forgetting it produces the familiar effect of the background sliding around behind a modal on a phone.

It also does not animate. Transitions on an element that switches between displayed and not displayed require the newer CSS features for that, so treat any animation as an enhancement.

Naming the dialog

A dialog should have an accessible name so it is announced as something meaningful rather than just as a dialog. An aria-labelledby attribute pointing at the heading inside it is the usual approach.

Where the dialog has descriptive text as well, an aria-describedby attribute pointing at it means the explanation is announced alongside the name rather than requiring the user to explore.

When not to use a modal at all

Modals interrupt. They demand a decision before anything else can continue, which is appropriate for a genuine confirmation and inappropriate for most of what they are used for.

Newsletter prompts, cookie notices and promotional overlays are all modals in practice and rarely need to be. Content that could sit inline, in a disclosure panel, or on its own page is usually better there, particularly on a phone where a modal frequently covers the entire screen and the close control is the hardest thing to find.