Modal

Usage

Use a modal when the dispatcher must finish or cancel a short task before going on: reassign a mechanic, edit a service interval, confirm a deletion. The rest of the page becomes inert until it closes.

• Modal dialog — a focused task with a form or a decision. Keep it to one screen of content; long flows belong on a page.
• Alert dialog — a confirmation that interrupts: destructive or irreversible actions only ("Delete work order WO-1042?").
• Don't use a modal for information the user doesn't have to act on (use an alert or toast), for filters (use a drawer or popover), or open a modal from a modal.

Content: the title states the task or the consequence as a question ("Reassign work order WO-1042", "Delete work order WO-1042?"). Buttons are verb + object ("Delete work order", "Reassign mechanic"); the dismiss action is "Cancel", never "No" or "OK". Put the primary action at the inline end with Cancel beside it.

Anatomy

1. Backdrop — ::backdrop with --color-bg-overlay
2. Container — <dialog class="modal"> on the overlay surface, --overlay-radius and --overlay-shadow
3. Header — .modal__header: title .modal__title (an h2) and close button .modal__close; alert dialogs show a tone icon .modal__icon instead of the close button
4. Body — .modal__body, the only part that scrolls
5. Footer — .modal__footer: Cancel, then the primary action at the inline end

Examples

Open dialogs are previewed in the page with the docs-only .is-preview class; every demo also has a real trigger that opens the dialog in the top layer with commandfor/command="show-modal", without JavaScript.

<button type="button" class="btn btn--secondary" commandfor="dlg-reassign" command="show-modal">Reassign mechanic</button>

<dialog id="dlg-reassign" class="modal" aria-labelledby="reassign-title" aria-describedby="reassign-desc" closedby="any">
  <div class="modal__header">
    <h2 class="modal__title" id="reassign-title">Reassign work order WO-1042</h2>
    <button type="button" class="btn btn--ghost btn--sm modal__close" commandfor="dlg-reassign" command="close" aria-label="Close">
      <svg class="btn__icon" aria-hidden="true" focusable="false"><use href="#icon-x"></use></svg>
    </button>
  </div>
  <div class="modal__body"><p id="reassign-desc">…</p></div>
  <div class="modal__footer">
    <button type="button" class="btn btn--ghost" commandfor="dlg-reassign" command="close">Cancel</button>
    <button type="button" class="btn btn--primary">Reassign mechanic</button>
  </div>
</dialog>

<!-- Sizes and variants -->
<dialog class="modal modal--sm">…  <dialog class="modal modal--lg">…
<dialog class="modal modal--scroll">…  <dialog class="modal modal--fullscreen-mobile">…

<button type="button" class="btn btn--destructive" commandfor="dlg-delete" command="show-modal">Delete work order</button>

<dialog id="dlg-delete" class="modal modal--alert modal--danger" role="alertdialog"
        aria-labelledby="delete-title" aria-describedby="delete-desc">
  <div class="modal__header">
    <span class="modal__icon" aria-hidden="true"><svg focusable="false"><use href="#icon-trash"></use></svg></span>
    <h2 class="modal__title" id="delete-title">Delete work order WO-1042?</h2>
  </div>
  <div class="modal__body"><p id="delete-desc">… This can't be undone.</p></div>
  <div class="modal__footer">
    <button type="button" class="btn btn--ghost" commandfor="dlg-delete" command="close" autofocus>Cancel</button>
    <button type="submit" class="btn btn--destructive" form="delete-wo-1042">Delete work order</button>
  </div>
</dialog>

API

Do and don't

Accessibility

• Role: native <dialog> opened with showModal() (via the invoker) is a modal dialog — top layer, inert background, Esc handling. Alert dialogs add role="alertdialog" (APG Alert Dialog).
• Name and description: aria-labelledby → the title; aria-describedby → the main paragraph, read on open.
• Focus: moves to the first focusable element or the autofocus one (Cancel in alert dialogs, the least destructive action). On close the browser returns focus to the invoker.
• No light dismiss on alert dialogs or dialogs with forms: an accidental click must not lose input.
• The scrolling body is focusable (tabindex="0" + aria-label) so keyboard users can scroll it.
• Fallback: browsers without invoker commands need the shared invoker polyfill that maps command to showModal()/close().
• Forced colors: the dialog keeps a CanvasText border.

Tokens