Skip to content

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

html

Modal with initial focus, sheet on small screens

html

Custom header with an accessible name

html

Not dismissible

html

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.

html

Responsive

With responsive-sheet, the panel becomes a full-width bottom sheet on windows narrower than 640 px.

html

Close button

Without showClose, the header has no X. It closes with Esc, the backdrop, or a button of your own.

html

Footer

The footer with actions stays fixed below the body.

html

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 → banner or note on 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) or aria-label provides 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-sheet class 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.

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

The trigger uses invoker commands (`command` and `commandfor`), which browsers ship from Chrome 135, Firefox 144, and Safari 26.2. In older ones, Core’s JS runs the commands on the dialog. If you didn’t load that JS, the button doesn’t open it and you need to call `dialog.showModal()` from your own code.

From the CDN, without a build, load taisho.modal.css along with taisho.base.css. Also load:

  • taisho.button.css
  • taisho.icon.css
  • taisho.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 with showModal(). 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 inert natively. Screen readers and focus can’t reach the content behind the modal.
  • Accessible name. With the component’s own title, the <dialog> carries aria-labelledby pointing to it. With a custom header, the name has to come from aria-labelledby (pointing to the header’s title) or aria-label on the <dialog>. With neither (a title attribute also counts as a name), Core warns in the console when the page is served from localhost.
  • Esc closes the dialog unless it isn’t dismissible. The × button exposes an aria-label and 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, the cancel event 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 every showModal(). No JS needed.
  • responsive-sheet only 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' overflow and z-index don’t affect it.

Keyboard

On top of what the browser already does (Tab moves focus, Enter activates a button).

Key What it does
EscCloses 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.