Modal
A modal takes over the page for one short task. On these sites that means searching on a phone, looking through a gallery, and sending feedback on a staging site. Almost nothing else belongs in one.
Show code
<button type="button" class="btn-secondary" data-dialog-open="leave">Leave the list</button>
<dialog class="sn-dialog" id="leave" aria-labelledby="leave-title">
<h2 id="leave-title">Leave the mailing list?</h2>
<p>You won’t get the next issue. You can sign up again at any time.</p>
<div class="sn-dialog-actions">
<button type="button" class="btn-secondary" data-dialog-close>Stay on the list</button>
<button type="button" class="btn-primary" data-dialog-close>Leave the list</button>
</div>
<button type="button" class="sn-dialog-close" data-dialog-close aria-label="Close">×</button>
</dialog> When to use it
- One short task that has to be finished or put down before anything else: a question to answer, a picture to look at, a few fields.
- Something the person asked for, by pressing a button.
Use something else when:
- It is news, not a task ("Saved"): a toast. A note that stays: a notice.
- It is a long form, or several steps: a page.
- It is a few words about a control: a tooltip.
- It is a choice from a list beside a field: a drop-down. The date field's calendar is a pop-over, and only a sheet on phones.
How it works
- The browser's own
<dialog>, opened withshowModal(). The browser keeps the focus inside it, closes it on Escape, makes the page behind unreachable, and puts the focus back on the button that opened it. class="sn-dialog"gives it the card, the dimmed page and its place. A button withdata-dialog-open="id"opens it; a button withdata-dialog-closecloses it; so does a click on the dimmed page.- It has a visible heading, and
aria-labelledbypoints at it, so the dialog is announced by its heading. - The focus starts on the first button or field of the task. The close button is drawn top right but comes last in the markup, so the way out is never the first thing read.
- The page behind doesn't scroll, on iPhones too. On a phone with the keyboard up, the dialog fits the part of the screen that is left.
- Not printed.
The dialogs these sites have
- Search on phones, and on sites with no search box in the header.
- The picture viewers.
- Feedback on a staging site's review tools.
Each is the same element and keeps the same rules. They were built before .sn-dialog and carry their own styles; a new dialog starts from the class.
Do and don't
Do
- Keep it to one task with one main button
- Always offer a visible way out
- Give it a visible heading that says what it is for
- Name the buttons for what they do ("Leave the list"), not Yes and No
Don't
- Open a modal the visitor didn't ask for
- Put a long form or a second modal inside it
- Build one from a
div: the focus and the page behind are then yours to manage
Accessibility
What it does for you
- The browser’s own
dialog, opened as a modal: the focus stays inside, Escape closes it, and the page behind is out of reach of the keyboard, the pointer and screen readers. - Named by its visible heading (
aria-labelledby). - The focus starts on the first button or field of the task. The close button is last in the markup, drawn top right.
- On closing, the browser puts the focus back on the button that opened it.
- A click on the dimmed page closes it; a click on the dialog’s own edge does not.
- The page behind doesn’t scroll, and on a phone with the keyboard up the dialog fits the screen that is left.
What you need to do
- A heading that says what the dialog is for, with
aria-labelledbypointing at it. - Buttons named for what they do.
- One task. If it needs a second dialog, it needs a page.
- Open it from a button the person pressed, never by itself.
Keyboard
| Key | What it does |
|---|---|
| Enter or Space | On the button: opens the dialog. |
| Tab and Shift+Tab | Move through the dialog’s controls and go round. They never reach the page behind. |
| Escape | Closes it. The focus returns to the button. |
What a screen reader is told
- "Leave the mailing list?, dialog" on opening, then the control with the focus.
- Nothing of the page behind while it is open.
This is what the browser reports to assistive technology. What each screen reader then says varies, and has not been listened to yet.
WCAG 2.2
| Criterion | Level | How this meets it |
|---|---|---|
| 2.1.1 Keyboard | A | Opened, used and closed by keyboard. |
| 2.1.2 No Keyboard Trap | A | Escape and the close button always leave. |
| 2.4.3 Focus Order | A | Focus goes in on opening and back to the opener on closing. |
| 2.4.7 Focus Visible | AA | The site’s 2px ring on every control in it. |
| 2.5.8 Target Size (Minimum) | AA | The close button is 40px. |
| 4.1.2 Name, Role, Value | A | A dialog by role, named by its heading. |
The criteria this component has a part in. A page that uses it still has to meet the rest.
Checked
| Check | How | Result |
|---|---|---|
| Automated (axe-core) | WCAG 2.0, 2.1 and 2.2 rules at A and AA, the page in light and in dark | Passed Nothing found, light or dark |
| Narrow screen | No sideways scrolling at 320px wide (WCAG 1.4.10) | Passed No sideways scrolling |
| Keyboard and what the browser reports | Real key presses on the live example, and the role, name and state given to assistive technology | Passed 11 of 11 checks pass |
| On paper | Somnia’s print check: no overlaps, stranded headings or controls on the page | Passed No faults on 6 sheets |
| Screen reader | Listened to by a person, in VoiceOver and NVDA | Not yet Not yet checked by a person |
The 11 checks made with the keyboard, on the example at the top of this page:
- Passed Enter on its button opens it: a modal dialog named by its heading
- Passed Space opens it too
- Passed The focus starts on the first button of the task, not on Close
- Passed Tab goes through its buttons, Close last, and round again; it never reaches the page behind
- Passed Escape closes it and the focus goes back to the button that opened it
- Passed Enter on a button inside closes it, and the focus goes back
- Passed A click on the dimmed page closes it; a click on the dialog’s own edge does not
- Passed While it is open the page behind can’t take the focus and doesn’t scroll
- Passed The close button is named "Close" and is 40px
- Passed Keyboard focus shows a 2px ring on its buttons
- Passed At 320px wide the dialog fits the screen
Run by script on against Somnia DS 1.89.0, in Chromium with axe-core 4.14.0. How these checks work, and every component's results.
Not yet checked
- How it sounds in a screen reader (VoiceOver, NVDA, TalkBack) has not been checked by a person. The roles, names and states the browser reports are checked by script; what is actually spoken is not.
- Windows high contrast (forced colours) has not been looked at by a person.
.sn-dialogis new in 1.88.0 and no page on any site uses it yet. Search on phones, the picture viewers and staging feedback are dialogs built before it, each with its own styles.- A dialog taller than the screen scrolls inside itself. Not tried with a long one by a person.
Evidence
Where it's used
| Where | For |
|---|---|
| These docs | The example on this page. No site has a .sn-dialog yet. |
| Every site | The same element, with their own styles: search on phones, the picture viewers, and feedback on staging. |
What we saw, and what changed
| When | What we saw | What changed |
|---|---|---|
| The page behind an open dialog scrolled. | It stays put, for every modal dialog (1.22.1), on iPhones too (1.68.0). | |
| On a phone the keyboard covered a dialog’s last field. | A dialog fits the part of the screen the keyboard leaves, and the field being typed in stays in view (1.72.0). | |
| A sign-in dialog asked for an email and a password and could never let anyone in. | Removed (1.77.1). | |
| This page’s example was a drawing of a dialog, with nothing to check. | .sn-dialog: a real one, opened and closed by two attributes (1.88.0). |
From building and using it on real sites, each entry taken from the changelog or the build's own notes. This is observation by the studio and its clients, not research sessions with users.
What it rests on
- ARIA Authoring Practices: Dialog (Modal): Focus moves into a dialog, stays there, and returns to what opened it; Escape closes it; it is named by its title.
What we don't know yet
- With no site using the class, nothing is known about how it does in use.
- The three older dialogs have not been moved onto it.