Modal
A centered dialog that interrupts for a focused task—a form, a detail view, a light confirmation. It’s built on the native <dialog>, so it traps focus, closes with Esc, and makes the background inert.
Overlays · TaishoDS Core, in plain HTML.
Examples
One working example per case. Each example is the HTML of its preview—copy it as is, and with Core’s CSS and JS loaded, it looks and works the same.
Confirmation with actions
Modal with initial focus, sheet on small screens
Custom header with an accessible name
Not dismissible
Class reference
Every value of each modifier, with its HTML ready to copy.
Size
Panel width: sm, md, or lg. Open each one to see it.
Responsive
With responsive-sheet, the panel becomes a full-width bottom sheet on windows narrower than 640 px.
Close button
Without showClose, the header has no X. It closes with Esc, the backdrop, or a button of your own.
Footer
The footer with actions stays fixed below the body.
When to use
- The task is short and self-contained. It fits without scrolling and gets done without leaving.
- Interrupting the flow is justified, because what’s underneath can wait.
- It’s fine for the user to close it by clicking the backdrop or pressing Esc.
When not to use
- The decision is destructive or irreversible, and the dialog must not close by accident →
alert-dialog. - The content is long or secondary, or the context beside it is worth keeping (filters, cart, navigation) →
drawer. - It’s a notice that doesn’t need an immediate response →
bannerornoteon the page itself.
Do
- Give it a visible title. It’s the dialog’s accessible name and orients whoever lands there. With a custom
header,aria-labelledby(pointing to its title) oraria-labelprovides the name. - One task per modal. If a second step shows up, rethink the flow instead of nesting.
- If there’s a field the user will fill in first, add
autofocus.showModal()focuses it every time the dialog opens. - On small screens, the
responsive-sheetclass on the<dialog>turns it into a bottom sheet that’s easier to reach with a thumb.
Don’t
- Don’t open a modal from another modal. Stacked top-layer elements confuse focus and Esc.
- Don’t use it for confirmations that require a yes or no—for those, the backdrop must NOT dismiss.
Related
TaishoDS Core
Doesn’t need our JavaScript—the browser handles it.
It’s a <dialog> with invoker commands (commandfor). It opens, closes, traps focus, and paints the backdrop without a line of JavaScript (in a browser with invoker commands).
Limitation
From the CDN, without a build, load taisho.modal.css along with taisho.base.css. Also load:
taisho.button.csstaisho.icon.csstaisho.spinner.css
For how Core works in general, see Behavior.
Accessibility
Implements the Modal Dialog pattern from the WAI-ARIA APG.
- A
<dialog>element opened withshowModal(). The browser provides the dialog role, traps focus, and returns it to the trigger on close. In WebKit, when the dialog was opened with the mouse, focus does not return to the trigger on close, because Safari does not focus a button on click. - The background becomes
inertnatively. Screen readers and focus can’t reach the content behind the modal. - Accessible name. With the component’s own title, the
<dialog>carriesaria-labelledbypointing to it. With a custom header, the name has to come fromaria-labelledby(pointing to the header’s title) oraria-labelon the<dialog>. With neither (atitleattribute also counts as a name), Core warns in the console when the page is served fromlocalhost. - Esc closes the dialog unless it isn’t dismissible. The × button exposes an
aria-labeland is hidden when it isn’t dismissible. - Not dismissible:
closedby="none"on the<dialog>. The browser doesn’t close it with Esc or the backdrop. Where the browser ignores it, thecancelevent and the Esc keystroke are prevented. Only its own buttons close it. - While the dialog is open, the page behind it doesn’t scroll and keeps the scrollbar’s space (
scrollbar-gutter: stable), so the content doesn’t shift. - Initial focus. The browser focuses the child with
autofocus(or, if there isn’t one, the first control) on everyshowModal(). No JS needed. responsive-sheetonly changes the position and the animation below 640px. The role, the focus trap, and Esc stay the same.- It lives in the browser’s top layer, so its ancestors'
overflowandz-indexdon’t affect it.
Keyboard
On top of what the browser already does (Tab moves focus, Enter activates a button).
| Key | What it does |
|---|---|
| Esc | Closes the dialog. If it isn’t dismissible (closedby="none"), it does nothing, not even on a second Esc in a row. |
Verification
What was actually tested. Anything that wasn’t tested says so—we’d rather say “not verified” than claim too much.
- axe WCAG 2.2 A + AA in a real browser, in light and dark mode, before every release.
- keyboard Key map documented above, checked against the component.
- screen reader Not verified with a screen reader. Test it in your own combination of components, not just here, where each one appears alone and on its happy path.