Skip to content

Dialog

Stable Available in release assets

Present a focused task in the browser top layer while preserving native dialog semantics, Escape dismissal, and form method=dialog submission.

Dialog primary example

Show code
<dialog class="thin-dialog" open aria-labelledby="review-title">
  <div class="thin-stack">
    <h2 id="review-title">Confirm order details</h2>
    <p>Review the delivery details before confirming this order.</p>
    <form class="thin-cluster" method="dialog">
      <button class="thin-button" value="confirm">Confirm order</button>
      <button class="thin-button" data-variant="secondary" value="cancel">Go back</button>
    </form>
  </div>
</dialog>

Each authored example uses the production assets and includes copyable markup.

Native showModal focus and Escape behavior remain canonical.

Show code
<dialog class="thin-dialog" open aria-labelledby="review-title">
  <div class="thin-stack">
    <h2 id="review-title">Confirm order details</h2>
    <p>Review the delivery details before confirming this order.</p>
    <form class="thin-cluster" method="dialog">
      <button class="thin-button" value="confirm">Confirm order</button>
      <button class="thin-button" data-variant="secondary" value="cancel">Go back</button>
    </form>
  </div>
</dialog>

External trigger

Optional dialog behavior connects data-dialog-open controls and restores focus on close.

Show code
<p><button class="thin-button" type="button" data-dialog-open="settings-dialog">Open settings</button></p>
<dialog class="thin-dialog" id="settings-dialog" aria-labelledby="settings-title">
  <h2 id="settings-title">Settings</h2>
  <form method="dialog">
    <button class="thin-button">Close</button>
  </form>
</dialog>

Non-modal dialog

A dialog opened with show() remains in the page without blocking the rest of the document.

Show code
<dialog class="thin-dialog" aria-labelledby="note-title">
  <h2 id="note-title">Editor note</h2>
  <p>This dialog can stay open beside the page.</p>
  <form method="dialog">
    <button>Close</button>
  </form>
</dialog>

Anatomy

  • Native dialog with class="thin-dialog"
  • Accessible heading
  • Authored body content
  • Native actions or form method=dialog
  • Optional external trigger

Variants and sizes

  • Modal — shown above
  • Non-modal — shown above
  • External trigger — shown above

Rendered fixtures exercise authored content and constrained layouts with the same production assets.

  • Closed
  • Open
  • Long localized copy
  • Narrow viewport
  • 200% and 400% zoom
  • Forced colors
  • Nested dialogs

Structured state fixtures are not published for this item yet.

Interaction and keyboard behavior

Native dialog behavior owns showModal, show, close, Escape, focus containment, and form method=dialog. Optional dialog behavior coordinates data-dialog-open triggers and restores focus after native close.

Accessibility

Name the dialog with aria-labelledby or aria-label. Keep essential tasks reachable in the page when JavaScript or native dialog presentation is unavailable. Autofocus the safest action only for blocking confirmations.

Contract
DIALOG
Basis
Native <dialog>; APG dialog guidance is secondary to native behavior
Behavior guarantees
  • Uses native <dialog> and method="dialog"; the trigger helper only coordinates opening, initial focus, and return focus.
  • Rejects ambiguous or unnamed targets and keeps the authored link fallback when modal presentation is unavailable.
  • Focuses an available control on open and restores a connected trigger after close.
Evidence
  • tests/unit/behaviors/dialog.test.ts
  • tests/unit/library/advanced-component-contracts.test.ts

API

Use dialog.thin-dialog with labelled content and native form method=dialog actions. Load dialog behavior once per document when using data-dialog-open or data-dialog-close.

Behavior tier: native

Structured host, property, and example tables are not authored for this item yet. Use the summary above and the primary example.

Fallback

Essential tasks require an in-flow fallback such as a dedicated page, inline form, or ordinary link destination.

Assets and dependencies

  • /components.css
  • /behaviors.js

Dependencies: None

Source: packages/ui/src/items/dialog/style.ts

Stability evidence

  • Native dialog semantics, optional trigger coordination, and in-flow fallback contract: test:tests/unit/behaviors/dialog.test.ts
  • Complete item-specific API, fallback, and difficult-state documentation: test:tests/unit/library/overlays-feedback-stable.test.ts
  • Cross-theme, density, localized, narrow-container, zoom, and forced-colors fixture: review:site/src/pages/quality/index.astro#quality-review

Composition

Derived from the examples and style specs, not authored.

Composes

Used by