Dialog

import "@taprootio/espalier/dialog";

<esp-dialog>

Used to focus content modally. By default, on large screens the dialog content is centered horizontally near the top of the screen. On small screens, the content always tries to take up the full screen width.

When opened, the dialog:

Moves focus to the first [autofocus] element inside the slotted content, then the first focusable element (or the dialog container itself if none is found).
Traps focus so that Tab and Shift+Tab cycle only through elements inside the dialog.
Closes when the user presses Escape.
Marks all sibling content as inert to prevent screen reader and keyboard access to the page behind the overlay.
Restores focus to the element that was focused before the dialog was opened.

Slots

<esp-dialog> has a slot:

Default

Place content to show modally in the default slot.

Dialogs work well as containers for complex forms. Picker menus, inputs, and other interactive controls render correctly inside the dialog overlay.

Attributes

<esp-dialog> has the following attributes:

full-screen

full-screen has a default value of false.

If true, the dialog will take up the full screen. On small screens, the dialog will always be full screen.

Methods

<esp-dialog> has the following methods:

toggleOpen

Show or hide the dialog content. When opening, focus moves into the dialog and sibling content is marked inert. When closing, focus is restored to the element that was focused before the dialog opened.

Dispatches lifecycle events:

esp-dialog-opened after the dialog is fully rendered and focus has moved in.
esp-dialog-closing (cancelable) before the close begins.
esp-dialog-closed after the close completes.

Events

<esp-dialog> emits the following events:

esp-dialog-opened

esp-dialog-opened is of type CustomEvent<{}>.

Fired after the dialog has been promoted to its final DOM position, rendered, and focus has moved in. Safe to initialize third-party widgets (e.g. Stripe Elements) or measure layout at this point.

esp-dialog-closing

esp-dialog-closing is of type CustomEvent<{ reason: "escape" | "close-dialog" | "api" }>.

Fired before the dialog begins closing. Call event.preventDefault() to cancel the close (e.g. for unsaved-changes confirmation). The reason indicates what triggered the close: "escape" for the Escape key, "close-dialog" for a esp-form-dialog-close-requested event from slotted content (typically <esp-form method="dialog">), or "api" for a direct toggleOpen() call.

esp-dialog-closed

esp-dialog-closed is of type CustomEvent<{ reason: "escape" | "close-dialog" | "api" }>.

Fired after the dialog has fully closed, inert state has been restored, and focus has returned to the previously focused element. Safe to tear down resources.

CSS Properties

<esp-dialog> has the following CSS properties:

--esp-color-dialog-bg

The background color of the dialog overlay.

--esp-dialog-bg-opacity

The opacity of the dialog overlay background.