The <dialog> element in HTML: a practical guide, examples, and best practices

04-12-2025 - 👤 Andrés Cruz

The HTML5 <dialog> element is one of those little gems that many developers overlook until they need it. And when you try it for the first time, you wonder how you lived so many years creating modals with plugins, layers, overlays, and hundreds of lines of JavaScript.

The first time I used it, I was surprised at how simple it was to get a functional modal without external libraries: you declare it, call show() or showModal(), and you already have a native pop-up window ready to work.

I find it very curious that functionalities that are usually not basic, which is what HTML usually offers, simply containers, texts, fields that we then put together to have a component, but in the case of the dialog it is curious, since it is a complete component between the container/dialog and the base functionality.

In this guide, I'm going to teach you how it works, when to use it, what methods it offers, how to style it, how to close it without JavaScript, and how to keep it accessible for all your users.

The <dialog> element (dialog) defines a dialog box or simply a new window; its appearance and operation are similar to that of a div with a background color; as you can see, it allows you to create modals on a web page without using any plugin in the process; modals, or also known as pop-up windows, allow users to confirm operations simply and much more visually than the confirm provided in JavaScript.

Previously we looked at the HTML CSS progress bar

What the <dialog> element is and what it is for

The <dialog> element represents a dialog window or pop-up box within a page. It can contain text, images, forms, buttons... practically any HTML content.

In my experience, it works very similarly to a div with a custom background, but with native superpowers: background blocking (in modal mode), its own events, built-in methods, and accessible behavior by default.

Modal Dialogs vs Non-Modal Dialogs

Type Function Interaction
Modal (showModal()) Forces the user to attend to the window. The background becomes inert, cannot be interacted with.
Non-modal (show()) Shows info without blocking the flow. The user can continue using the page.

Below is the table of contents we will cover to learn how this native HTML5 modal works:

Using the <dialog> element in HTML.
Attributes of the <dialog> element.
Methods of the <dialog> element.
Events of the <dialog> element.
Adding style to the <dialog> element.
Browsers that support the <dialog> element.

Using the dialog element in HTML

dialog is an HTML5 element that allows you to establish a new section independently within the body where it is embedded; to use the dialog element we have to:

<body> <section> <dialog></dialog> </section> </body>

Although you can place as many nestings as you want, or place it as a direct child of the body:

<body> <dialog></dialog> </body>

Its use, in short, consists of, once the HTML is defined as we did before, using the show() or showModal() methods via JavaScript and finally the close() method to hide the dialog again.

It can be placed anywhere in the body, as a direct child or within other sections.

The dialog is a very flexible component that can be placed even within complex components without breaking styles.

Show and hide dialogs: show(), showModal() and close()

The three key methods:

dialog.show();      
// non-modal dialog 
dialog.showModal(); 
// modal dialog 
dialog.close();     
// closes the dialog

If you add the open attribute directly in HTML, it will appear visible from the start:

<dialog open>Content visible from the start</dialog>

Attributes of the <dialog> element

Like all elements in HTML, we can complement them with attributes according to our needs; in the case of the dialog element, it has its own attribute as we see below:

open: If this attribute is set, it specifies that the modal or dialog is active and visible; it also indicates that the user can interact with it.

Other interesting attributes:

Indicates that the dialog is active. Without it, the dialog is hidden by default (similar to a display: none).
Closedby attribute
Implemented in some experimental implementations. Allows closing the dialog:
- any: click outside or Escape key
- closerequest: only close keys/requests
- none: does not allow automatic closing
Recommended ARIA attributes
- aria-labelledby="idOfTitle"
- role="dialog" or role="alertdialog" for critical messages

This improves the experience for screen readers.

View example Download source

Methods of the <dialog> element: show() vs showModal()

As we mentioned before, the dialog element has three methods, two of them to display the dialog and one of them to hide it as we define below:

show(): This method is used to display the dialog; it has the same behavior as adding the open attribute to the dialog.
showModal(): This method is used to display the dialog; unlike the first, this method blocks all content except the dialog by interposing a transparent window.
close(): This method is used to hide the dialog or modal; it has the same behavior as removing the open attribute from the dialog.

View example Download source

Events of the <dialog> element

The dialog element has a single event that executes when the dialog is closed:

dialog.addEventListener('close', function() { //*** do something });

Styling the <dialog> element

As a final point, we will address the issue of styles, which, like any other HTML element, we can apply all the styles we like and make our dialog or pop-up window look the way we want, overwriting its default appearance by defining rules that alter its position, size, shape, rounded corners. We can create a header for the title, another container as a body for the content, modify the close button, and many things you can think of, as you can see in this example:

View example Download source

Many browsers apply their own styles (background color, borders...).

But you can overwrite them without problem:

dialog { 
padding: 1.5rem; 
border: none; 
border-radius: 12px; 
box-shadow: 0 4px 30px rgba(0,0,0,0.3); 
}

When I designed my dialogs, I was able to create custom headers, footers, and buttons without difficulty, very similar to styling a div.

Background style with ::backdrop

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

Design examples

Centered modal
Floating notification (non-modal)
Confirmation with icon + dual button

Browsers that support the <dialog> element

Nowadays, compatibility is quite broad:

Browser Status
Chrome ✔ complete
Safari ✔ complete
Edge ✔ complete
Firefox ✔ modern support
Mobiles ✔ most

Extra: Working with forms inside the dialog

If you want to close a <dialog> without JavaScript, use:

<form method="dialog"> 
<button>Accept</button> 
</form>

I discovered this while trying the element for the first time, and I loved being able to do without the typical onclick="dialog.close()".

formmethod="dialog"

You can overwrite the method even if the parent form doesn't use it.

returnValue

If you submit a form inside the dialog:

<button type="submit" name="opcion">Send</button>

The final value will be:

dialog.returnValue === "opcion".

Extra: Accessibility and best practices

Accessibility is a strong point of the <dialog> element.

Focus management (focus trapping)

When opening a modal, the focus:

Is directed to the first focusable element.
Does not escape from the modal.
Returns to the element that opened it when it closes.

Keyboard flow control is much more natural than in "handmade" modals.

Use of inert

The background automatically becomes inert in modal mode. Do not add tabindex to the <dialog>.

When to use role="dialog" or role="alertdialog"

dialog: informative windows.
alertdialog: important messages, warnings, critical confirmations.

Frequently Asked Questions

What is the <dialog> element used for?
- To display native pop-up windows: modals, messages, forms, or informational panels.
What is the difference between show() and showModal()?
- show() does not block the background.
  showModal() blocks it and makes the page inert.
Can a dialog be closed without JavaScript?
- Yes, using method="dialog" or formmethod="dialog".
How do I style the modal background?
- With the ::backdrop pseudo-element.
Is it accessible by default?
- Yes, it handles focus, background blocking, and recommended ARIA roles.

Conclusion

The <dialog> element in HTML is a native, modern, and surprisingly powerful tool. In my experience, it allows you to build clean, accessible, and easy-to-maintain modals without relying on external libraries.

If you're building interactive interfaces—confirmations, quick forms, notices, or even floating panels—it's worth adopting it.

The next step, the map and area tags in HTML

I agree to receive announcements of interest about this Blog.

Learn how to use the