Prototype Library

Dialog

Modal dialog with backdrop, focus trap, Esc-to-close, and focus restore. Slot the body as default content and footer actions into slot="footer".

Inherited wc import '@esa/ecology/esa-dialog';

Preview

The default md dialog (480px). The close button, backdrop click, and Esc all dismiss it.

 
<button data-target="dlg-md">Open dialog</button>

<esa-dialog id="dlg-md" heading="Medium dialog">
  <p>The default md dialog. The close button, backdrop click, and Esc all dismiss it.</p>
  <button slot="footer" data-close="dlg-md">Close</button>
</esa-dialog>

Sizes

Five widths cover compact prompts through immersive, edge-to-edge flows.

The most compact dialog (280px), one step below sm. Tab cycles within; Esc closes.

A compact dialog (360px). Tab cycles within; Esc closes.

The default md dialog (480px).

A large dialog (640px) for richer content.

Edge-to-edge dialog for immersive flows.

 
<esa-dialog size="xs" heading="Extra small dialog">…</esa-dialog>
<esa-dialog size="sm" heading="Small dialog">…</esa-dialog>
<esa-dialog heading="Medium dialog">…</esa-dialog>
<esa-dialog size="lg" heading="Large dialog">…</esa-dialog>
<esa-dialog size="fullscreen" heading="Fullscreen dialog">…</esa-dialog>

API

PropTypeDefaultDescription
open boolean false Reflected attribute that drives visibility. Set imperatively via show() / close().
heading string '' Title shown in the header and used as the dialog accessible name.
show-close-button boolean true Renders the header close (×) button.
size 'xs' | 'sm' | 'md' | 'lg' | 'fullscreen' 'md' Panel width: 280 / 360 / 480 / 640px, or edge-to-edge.

Methods

PropTypeDefaultDescription
show() method — Opens the dialog and traps focus.
close() method — Closes the dialog, restores focus, and emits the close event.

Events

EventTypeDefaultDescription
close CustomEvent — Fired when the dialog closes (close button, backdrop click, or Esc). Bubbles and is composed.

Accessibility

  • The panel is role="dialog" with aria-modal="true"; heading provides the accessible name.
  • Focus is trapped while open — Tab and Shift+Tab cycle within the panel.
  • Opening stores the previously focused element and restores it on close.
  • Escape closes the dialog; the close button carries an aria-label.

Tokens

  • --color-surface-elevated · --color-border-light · --color-text-primary
  • --color-backdrop · --z-modal / --z-modal-backdrop
  • --radius-400 · --spacing-500 · --type-size-400 · --font-weight-semibold
  • --focus-ring-width / --focus-ring-color / --focus-ring-offset