Dialog - Material Design 3 Component Library

Basic Usage

Use the default basic variant for standard modal tasks. This is the recommended baseline because it balances flexibility, readable width, and predictable focus trapping.

Open Basic Dialog

<ds-dialog id="dialog-basic" variant="basic">
  <span slot="title">Settings</span>
  <p>Update your preferences.</p>
  <div slot="actions">
    <ds-button variant="text">Cancel</ds-button>
    <ds-button variant="text">Save</ds-button>
  </div>
</ds-dialog>

Initial Value

Pre-configure behavior with dismissal attributes for stricter workflows.

Open Configured Dialog

<ds-dialog
  variant="basic"
  dismiss-on-backdrop-click="false"
  dismiss-on-esc="false">
  <span slot="title">Review Required</span>
  <p>This dialog must be closed with explicit action buttons.</p>
</ds-dialog>

Variants

Dialog supports basic, alert, and full-screen variants.

Basic

Use when: You need a standard confirmation or short form.
Avoid when: The workflow is destructive and needs stronger caution semantics.

Alert

Use when: You need high-attention confirmation, especially destructive actions.
Avoid when: User input is long or multi-step.

Open Alert Dialog

Full-screen

Use when: Content or forms require full mobile viewport space.
Avoid when: A short, simple confirmation would suffice.

Open Full-screen Dialog

States

Dialog behavior changes by state. Open state traps focus and locks body scrolling, and dismissal attributes control whether Escape and backdrop interactions close the dialog.

Open State Demo

Close State Demo

const dialog = document.querySelector('#dialog-state');
dialog.show();
dialog.close();

Default (closed): No focus trap, no scroll lock.
Open: Focus is trapped in the modal and page scroll is locked.
Dismiss-locked: dismiss-on-backdrop-click="false" and dismiss-on-esc="false" require explicit actions.

Interactive Example

Open dialogs and inspect lifecycle events emitted by the component.

Open Interactive Dialog

Event log:

API Reference

Attributes

Attribute	Type	Default	Description
`variant`	string	`basic`	Dialog style: `basic`, `alert`, `full-screen`.
`open`	boolean	false	Controls whether the dialog is visible.
`dismiss-on-backdrop-click`	boolean	true	Closes when the scrim behind the dialog is clicked unless set to `false`.
`dismiss-on-esc`	boolean	true	Closes on Escape key unless set to `false`.

Events

Event	Detail	Description
`ds-dialog:open`	`{}`	Fired when dialog opens.
`ds-dialog:close`	`{}`	Fired when dialog closes.
`ds-dialog:confirm`	`{}`	Fired when default confirm button is clicked.

Methods

Method	Description
`show()`	Opens the dialog and traps keyboard focus.
`close()`	Closes the dialog and restores previous focus.

Slots

Slot	Description
`title`	Dialog title content.
`icon`	Optional icon in full-screen header.
`actions`	Action area for cancel/confirm controls.
(default)	Main dialog body content.

CSS Custom Properties

Property	Description
`--ds-dialog-close-button-size`	Close icon button size.
`--ds-dialog-icon-size`	Header icon size for full-screen variant.
`--ds-dialog-action-gap`	Spacing between action controls.
`--ds-dialog-surface-color`	Dialog panel background color (defaults to white).

Theming

Override dialog surface color without changing global tokens.

ds-dialog {
  --ds-dialog-surface-color: #ffffff;
}

Accessibility

Keyboard Map

Key	Context	Expected Result
`Tab` / `Shift+Tab`	Dialog open	Moves focus within dialog controls only.
`Escape`	Dialog open, dismiss enabled	Closes the dialog.
`Escape`	Dialog open, `dismiss-on-esc="false"`	Dialog remains open until explicit action.

Semantics and Focus

Uses role="dialog" with aria-modal="true".
Traps focus inside the dialog while open.
Restores focus to the previous element on close.
Supports keyboard dismissal with Escape (configurable).
Dims the page behind the dialog with the theme's scrim colour (--md-sys-color-scrim: 32% black, 60% in high-contrast).

Usage Guidelines

When to use: Use alert for short confirmations and destructive warnings.
When to use: Use basic for moderate forms and settings.
When to use: Use full-screen for long forms or mobile-first task flows.
When not to use: Avoid dialogs for persistent navigation, background monitoring, or non-blocking status updates.
Common mistakes: Stacking multiple dialogs, omitting explicit close actions in dismiss-locked flows, and using long uncontrolled content without full-screen variant.

Known Limitations

Dialog open state is managed per page and closes any other open dialogs automatically.