Dialog

Dialogs are modal windows built on the native <dialog> element. They trap focus, darken the backdrop, and support header, body, and footer sections. Opening and closing is handled via data-dialog-open and data-dialog-close attributes.

Tokens

Basic usage

<button class="button" type="button" data-dialog-open="my-dialog">Open dialog</button>

<dialog id="my-dialog" class="dialog">
  <div class="dialog-header">
    <h3 class="dialog-title">Dialog title</h3>
    <button class="dialog-close" type="button" aria-label="Close"><!-- close icon --></button>
  </div>
  <div class="dialog-body">
    <p>Dialog content here.</p>
  </div>
  <div class="dialog-footer">
    <button class="button is-faded" type="button" data-dialog-close>Cancel</button>
    <button class="button" type="button" data-dialog-close>Confirm</button>
  </div>
</dialog>

Confirmation dialog

A destructive action pattern with a danger-styled confirm button.

JavaScript

Include assets/js/dialog.js on any page using dialogs.

<script src="/assets/js/dialog.js"></script>

• data-dialog-open="dialog-id" on a trigger opens the dialog via showModal()
• data-dialog-close or .dialog-close inside a dialog closes it
• Clicking the backdrop also closes the dialog

Keyboard interactions

Accessibility notes

• Uses the native <dialog> element — focus trapping is handled by the browser
• The dialog title should use aria-labelledby pointing to the .dialog-title ID
• Close buttons must have aria-label="Close"
• The backdrop is created by the browser's ::backdrop pseudo-element

Do / Don't

Do:

• Use dialogs for actions that require confirmation or focused input
• Keep dialog content concise — one task per dialog
• Always provide a way to dismiss (close button + Escape + backdrop click)

Don't:

• Don't use dialogs for content that should be inline on the page
• Don't stack dialogs on top of each other
• Don't use dialogs for simple alerts — use callouts or toasts instead