Today I learned
Building accessible modal dialogs
As we all know, the web is not accessible, and that's a big bummer. A lot of
developers know way too less about accessibility, as we see if we look at the
HTML structure of websites, which often just consist of a ton of
On the other hand, a lot of companies don't pay for or don't have the budget for accessibility audits and improvements and the increased workload that comes with building accessible websites.
It's our job as developers to make accessibility a mandatory part of our work and create awareness for it. Sooner or later, new websites will have to be accessible by law.
I'm not an expert in accessibility, but I'm trying to improve my knowledge of it every day and with every new website or component I build.
Recently I built a modal dialog for a website, and here's everything I learned and applied to make it accessible.
Building accessible modal dialogs
There are a few key things to remember when building accessible modal dialogs. First of all, we need to ensure that the modal dialog can be accessed and navigated with a keyboard only.
Next, the keyboard focus should be managed properly. When opening the modal, the focus should be on the first focusable element inside the dialog. This enables keyboard users to navigate the modal dialog with the tab key right away.
Additionally, the elements behind the modal should be hidden from screen readers and not be focusable so users who use assistive technologies don't get lost in a sea of content.
To support this, the modal dialog should also be full-screen on mobile.
An obvious thing but often not implemented correctly is that the modal dialog should be closable with a certain close button and also be able to be closed with the escape key.
When you implement all of these things, you'll have a pretty accessible modal dialog and help many of people who use assistive technologies to access your content without any problems.
The important properties to enforce these things are the following:
First and foremost, if you're not using the
<dialog> element, you need to give your modal
role="dialog" attribute. This tells screen readers that the element
is a dialog and not just a regular div. The proper HTML element for your dialog
can be a
div or a
You also need to give your modal dialog the
aria-modal="true" attribute. This
tells screen readers that the dialog is modal and that the user needs to
interact with it before they can continue.
It also helps with getting lost in content, which I talked about earlier by limiting the navigation to the modal dialog content and hiding elements in the background.
aria-labelledby and aria-describedby
Next, you need to give your modal dialog an
aria-labelledby attribute with the
id of the title of the dialog. This tells screen readers which title belongs to
If you don't have a descriptive title element inside your modal dialog, you can
aria-label attribute instead.
If you have a description for your modal dialog, you can use the
aria-describedby attribute to tell screen readers which element contains the
Often, close buttons do not consist of descriptive text like "close". Instead,
icons, svgs, or images are used. In this case, you need to give the close button
aria-label="close modal" attribute to tell screen readers what the button
There exists a new HTML5 element called
<dialog>. It was introduced in
Chromium 37 back in 2014. Unfortunately,
it's not yet widely supported by all browsers ↗,
but we may be able to use it without any polyfills very soon. So if you're just
looking to support modern browsers, you can use it right now.
It then can be used instead of
role="dialog" because it's the semantic html5
Sources and further reading:
- Technique: Accessible modal dialogs ↗
- Modal Dialog Example ↗
- The a11y Monthly: Making modals accessible ↗
If you want to support me, you can buy me a coffee. I would be very happy about it!☕️ Buy me a coffee ☕️
I wish you a wonderful day! Marco