Preview brand Custom

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.

Beta

Leave the mailing list?

You won’t get the next issue. You can sign up again at any time.

A real dialog. (This example leaves no list.)
Show code
html
<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">&times;</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 with showModal(). 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 with data-dialog-open="id" opens it; a button with data-dialog-close closes it; so does a click on the dimmed page.
  • It has a visible heading, and aria-labelledby points 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-labelledby pointing 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

KeyWhat it does
Enter or SpaceOn the button: opens the dialog.
Tab and Shift+TabMove through the dialog’s controls and go round. They never reach the page behind.
EscapeCloses 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

CriterionLevelHow this meets it
2.1.1 KeyboardAOpened, used and closed by keyboard.
2.1.2 No Keyboard TrapAEscape and the close button always leave.
2.4.3 Focus OrderAFocus goes in on opening and back to the opener on closing.
2.4.7 Focus VisibleAAThe site’s 2px ring on every control in it.
2.5.8 Target Size (Minimum)AAThe close button is 40px.
4.1.2 Name, Role, ValueAA 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

CheckHowResult
Automated (axe-core)WCAG 2.0, 2.1 and 2.2 rules at A and AA, the page in light and in darkPassed
Nothing found, light or dark
Narrow screenNo sideways scrolling at 320px wide (WCAG 1.4.10)Passed
No sideways scrolling
Keyboard and what the browser reportsReal key presses on the live example, and the role, name and state given to assistive technologyPassed
11 of 11 checks pass
On paperSomnia’s print check: no overlaps, stranded headings or controls on the pagePassed
No faults on 6 sheets
Screen readerListened to by a person, in VoiceOver and NVDANot 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-dialog is 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

WhereFor
These docsThe example on this page. No site has a .sn-dialog yet.
Every siteThe same element, with their own styles: search on phones, the picture viewers, and feedback on staging.

What we saw, and what changed

WhenWhat we sawWhat 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

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.