HTML Dialog: How to Create a Dialog Box in HTML

Dialog boxes shouldn’t be overused, but when deployed at the right time, they can be critical for directing a user’s focus to the right information. And, from my experience, creating an HTML dialog box isn’t too difficult, as long as you know some JavaScript basics.

In this post, I’ll explain how to create the dialog element in HTML, how to open and close it with JavaScript, and some important accessibility considerations when using it. Let’s get started.

Table of Contents

• What is the Dialog Element in HTML?
• How to Add a Dialog Box in HTML
• Forms in HTML Dialog
• Focus and Accessibility in HTML Dialog
• HTML Dialog Browser Support

How to Add a Dialog Box in HTML

Let’s start by creating a basic dialog box and then explore the different ways we can customize it with HTML, CSS, and JavaScript, all languages to be familiar with when developing a website.

Basic Dialog HTML Syntax

To add a dialog box to a page, use the HTML <dialog> tag. I’ll start by adding a dialog box to a page with the <dialog> tag, along with some filler text inside the box and on the page.

See the Pen html dialog - no close button by HubSpot (@hubspot) on CodePen.

I’ll first call out the open attribute inside the <dialog> tag. When the open attribute is present, a (non-modal) dialog box will display. If not, the box will not display. In most cases, you won't display a dialog box on page load, so you don’t need to use the open attribute, but I’ve included it for demonstration purposes here.

While you can toggle the presence of the open attribute in the <dialog> tag to hide and reveal the dialog box, this isn’t recommended and there are better ways to toggle the box, which we’ll go into later.

Next, notice how the dialog box appears layered above the other page content. If the <dialog> tag is placed before the page content in the HTML, it will appear layered over this content. If the <dialog> tag is placed after some page content, it will not (barring any additional CSS). See below:

See the Pen html dialog - no close button, below page content by HubSpot (@hubspot) on CodePen.

There’s another thing about this box you might have noticed — you can’t close it! We’ll cover how to trigger and close dialog boxes next.

Opening and Closing the Dialog Box

The best way to open or close your dialog box is to use JavaScript. The HTML dialog element uses three JavaScript methods to control the dialog:

• .show() opens a non-modal dialog box. This allows users to interact with other elements on the page even while the dialog is open.
• .showModal() opens a modal dialog box. This prevents users from interacting with other page elements until the dialog is closed.
• .close closes the dialog box.

Let’s first see how to open and close a non-modal dialog box. In the example below, click the “Open Dialog” button to see the dialog, then “Close” to close it.

See the Pen html dialog - show/close by HubSpot (@hubspot) on CodePen.

It's pretty straightforward—we create variables for our dialog and buttons and set the dialog.show() and dialog.close() methods to be triggered by their respective buttons.

If you’re creating a dialogue, you need to provide a way to close the dialog, like a “Close” button for a positive user experience. Even though a user can also close a dialog with the escape key if opened with .showModal(), they may not realize this and will think they’re stuck on the dialog.

We're committed to your privacy. HubSpot uses the information you provide to us to contact you about our relevant content, products, and services. You may unsubscribe from these communications at any time. For more information, check out our Privacy Policy.

Free Guide: 25 HTML & CSS Coding Hacks

Tangible tips and coding templates from experts to help you code better and faster.

• Coding to Convention
• Being Browser-Friendly
• Minimizing Bugs
• Optimizing Performance

Download for free

Loading your download form

You're all set!

Click this link to access this resource at any time.

Access now

Learn more

Also, notice how you can interact with the page elements outside of the dialog (e.g., highlighting page text) because we used the .show() method.

Next, let’s see how to do the same thing with a modal dialog with the .showModal() method, which prevents users from interacting with the rest of the page when the dialog is open:

See the Pen html dialog - showModal/close by HubSpot (@hubspot) on CodePen.

When using this method, we can’t interact with other parts of the page when the dialog is open. You close the dialog by clicking the “Close” button, but, unlike with the .show() method, a modal can also be closed by hitting the escape key.

Additionally, when .showModal() is used, the background is obscured. You can actually change how the background is obscured with CSS by targeting the pseudo-element ::backdrop. For example, instead of darkening the background, we could blur the background.

See the Pen html dialog - showModal/close, blur by HubSpot (@hubspot) on CodePen.

Forms in HTML Dialog

It’s common to include forms in dialog boxes (for instance, a contact form or newsletter signup).

If the <form> tag inside the <dialog> tag has method=“dialog”, then hitting the submit button will also close the dialog. Alternatively, you can add formmethod=“dialog” to the <button> tag for the submit button, and this will also close the dialog when clicked.

See the Pen html dialog - form modal by HubSpot (@hubspot) on CodePen.

Focus and Accessibility in HTML Dialog

When creating an HTML dialog element, it’s important to consider how its focus will work. On a web page, the element with focus is the one that can be controlled with the keyboard. A user can move the focus through page elements with the tab key. Understanding and ensuring proper focus is essential to ensure your pages are accessible to keyboard users.

When the dialog opens, the browser places focus on the first focusable element within the <dialog> tag. For example, if the dialog only contains a “Close” button and no other elements that take focus, this button will be focused on, which makes it easy for a keyboard user to close the dialog by hitting enter.

Try it with the example below — open the dialog, then hit enter to close it:

See the Pen html dialog - focus example by HubSpot (@hubspot) on CodePen.

When you close the dialog, the focus moves back to the element that opened it. In this case, that element is the “Open Dialog” button.

In other cases, you’ll have a dialog with other focusable elements, like additional buttons or text fields. For these dialogs, focus should be placed on the field that users should expect to interact with first.

Sometimes, you may want the focus to shift to an element that is not the first focusable element nested in <dialog>. If so, you can add the autofocus attribute to the element you want to adopt focus as soon as the dialog opens.

In the example below, the close button element (the X in the top left of the dialog) comes first in the HTML, but we want the text input area to receive autofocus so the user can fill it out. So, I’ve placed autofocus in the <input> tag.

See the Pen html dialog - focus example by HubSpot (@hubspot) on CodePen.

HTML Dialog Browser Support

The HTML dialog element is supported in all modern browsers.

Add dialog boxes with HTML.

If you add dialog boxes to your site, be sure to test them and ensure they can be closed with both the mouse and the keyboard controls. A properly working dialog can make the difference between a conversion and a bounce, so work on refining your boxes and only deploy them when the benefits outweigh the cost of stealing user focus.