Building a dialog component

In this post I want to share my thoughts on how to build color-adaptive, responsive, and accessible mini and mega modals with the &LTdialog> element. Try the demo and view the source!

If you prefer video, here’s a YouTube version of this post:

Overview #

The &LTdialog> element is great for in-page contextual information or action. Consider when the user experience can benefit from a same page action instead of multi-page action: perhaps because the form is small or the only action required from the user is confirm or cancel.

The &LTdialog> element has recently become stable across browsers:

I found the element was missing a few things, so in this GUI Challenge I add the developer experience items I expect: additional events, light dismiss, custom animations, and a mini and mega type.

Markup #

The essentials of a &LTdialog> element are modest. The element will automatically be hidden and has styles built in to overlay your content.

dialog>
…
&LT/dialog>

We can improve this baseline.

Traditionally, a dialog element shares a lot with a modal, and often the names are interchangeable. I took the liberty here of using the dialog element for both small dialog popups (mini), as well as full page dialogs (mega). I named them mega and mini, with both dialogs slightly adapted for different use cases. I added a modal-mode attribute to allow you to specify the type:

dialog id="MegaDialog" modal-mode="mega">&LT/dialog>
dialog id="MiniDialog" modal-mode="mini">&LT/dialog>

Not always, but generally dialog elements will be used to gather some interaction information. Forms inside dialog elements are made to go together. It’s a good idea to have a form element wrap your dialog content so that JavaScript can access the data the user has entered. Furthermore, buttons inside a form using method="dialog" can close a dialog without JavaScript and pass data.

dialog id="MegaDialog" modal-mode="mega">
form method="dialog">
…
button value="cancel">Cancel&LT/button>
button value="confirm">Confirm&LT/button>
&LT/form>
&LT/dialog>

Mega dialog #

A mega dialog has three elements inside the form: &LTheader>, &LTarticle>, and &LTfooter>. These serve as semantic containers, as well as style targets for the presentation of the dialog. The header titles the modal and offers a close button. The article is for form inputs and information. The footer holds a &LTmenu> of action buttons.

dialog id="MegaDialog" modal-mode="mega">
form method="dialog">
header>
h3>Dialog title&LT/h3>
button onclick="this.closest('dialog').close('close')">&LT/button>
&LT/header>
article>...&LT/article>
footer>
menu>
button autofocus type="reset" onclick="this.closest('dialog').close('cancel')">Cancel&LT/button>
button type="submit" value="confirm">Confirm&LT/button>
&LT/menu>
&LT/footer>
&LT/form>
&LT/dialog>

The first menu button has autofocus and an onclick inline event handler. The autofocus attribute will receive focus when the dialog is opened, and I find it’s best practice to put this on the cancel button, not the confirm button. This ensures that confirmation is deliberate and not accidental.

Mini dialog #

The mini dialog is very similar to the mega dialog, it’s just missing a &LTheader> element. This allows it to be smaller and more inline.

dialog id="MiniDialog" modal-mode="mini">
form method="dialog">
article>
p>Are you sure you want to remove this user?&LT/p>
&LT/article>
footer>
menu>
button autofocus type="reset" onclick="this.closest('dialog').close('cancel')">Cancel&LT/button>
button type="submit" value="confirm">Confirm&LT/button>
&LT/menu>
&LT/footer>
&LT/form>
&LT/dialog>

The dialog element provides a strong foundation for a full viewport element that can collect data and user interaction. These essentials can make for some very interesting and powerful interactions in your site or app.

Accessibility #

The dialog element has very good built-in accessibility. Instead of adding these features like I usually do, many are already there.

Restoring focus #

As we did by hand in Building a sidenav component, it’s important that opening and closing something properly puts focus on the relevant open and close buttons. When that sidenav opens, focus is put on the close button. When the close button is pressed, focus is restored to the button that opened it.

With the dialog element, this is built-in default behavior:

Unfortunately, if you want to animate the dialog in and out, this functionality is lost. In the JavaScript section I’ll be restoring that functionality.

Trapping focus #

The dialog element manages inert for you on the document. Before inert, JavaScript was used to watch for focus leaving an element, at which point it intercepts and puts it back.

After inert, any parts of the document can be “frozen” insomuch that they are no longer focus targets or are interactive with a mouse. Instead of trapping focus, focus is guided into the only interactive part of the document.

Open and auto focus an element #

By default, the dialog element will assign focus to the first focusable element in the dialog markup. If this isn’t the best element for the user to default to, use the autofocus attribute. As described earlier, I find it’s best practice to put this on the cancel button and not the confirm button. This ensures that confirmation is deliberate and not accidental.

Closing with the escape key #

It’s important to make it easy to close this potentially interruptive element. Fortunately, the dialog element will handle the escape key for you, freeing you from the orchestration burden.

Styles #

There’s an easy path to styling the dialog element and a hard path. The easy path is achieved by not changing the display property of the dialog and working with its limitations. I go down the hard path to provide custom animations for opening and closing the dialog, taking over the display property and more.

Styling with Open Props #

To accelerate adaptive colors and overall design consistency, I’ve shamelessly brought in my CSS variable library Open Props. In addition to the free provided variables, I also import a normalize file and some buttons, both of which Open Props provides as optional imports. These imports help me focus on customizing the dialog and demo while not needing a lot of styles to support it and make it look good.

Styling the &LTdialog> element #

Owning the display property #

The default show and hide behavior of a dialog element toggles the display property from block to none. This unfortunately means it can’t be animated in and out, only in. I’d like to animate both in and out, and the first step is to set my own display property:

dialog {
display: grid;
}

By changing, and therefore owning, the display property value, as shown in the above CSS snippet, a considerable amount of styles needs managed in order to facilitate the proper user experience. First, the default state of a dialog is closed. You can represent this state visually and prevent the dialog from receiving interactions with the following styles:

dialog:not([open]) {
pointer-events: none;
opacity: 0;
}

Now the dialog is invisible and cannot be interacted with when not open. Later I’ll add some JavaScript to manage the inert attribute on the dialog, ensuring that keyboard and screen-reader users also can’t reach the hidden dialog.

Giving the dialog an adaptive color theme #

While color-scheme opts your document into a browser-provided adaptive color theme to light and dark system preferences, I wanted to customize the dialog element more than that. Open Props provides a few surface colors that adapt automatically to light and dark system preferences, similar to using the color-scheme. These are great for creating layers in a design and I love using color to help visually support this appearance of layer surfaces. The background color is var(--surface-1); to sit on top of that layer, use var(--surface-2):

dialog {
…
background: var(--surface-2);
color: var(--text-1);
}
TheComedicComedian (prefers-color-scheme: dark) {
dialog {
border-block-start: var(--border-size-1) solid var(--surface-3);
}
}

More adaptive colors will be added later for child elements, such as the header and footer. I consider them extra for a dialog element, but really important in making a compelling and well designed dialog design.