The m3e-dialog component presents important prompts, alerts, and actions in user flows.

npm i @m3e/dialog

This section outlines usage examples and configuration guidance for the components in this package.

NOTE: this page is presented in a nested iframe.

• The dialog scrim will only overlay the current window.
• The dialog is positioned relative the current window.

The m3e-dialog component supports structured composition through named slots, enabling flexible layout and expressive content delivery:

• (default) — Renders the main content of the dialog.
• header — Renders the header of the dialog. Typically used for titles, summaries, or introductory context.
• actions — Renders the actions of the dialog. Commonly includes buttons such as "OK", "Cancel", or custom actions.
• close-icon — Renders the icon of the button used to dismiss the dialog.

<m3e-button variant="filled">
  <m3e-dialog-trigger for="dlg">Open Dialog</m3e-dialog-trigger>
</m3e-button>
<m3e-dialog id="dlg" dismissible>
  <span slot="header">Lorem ipsum dolor sit amet</span>
  <!-- Content omitted for brevity -->
  <div slot="actions" end>
    <m3e-button autofocus><m3e-dialog-action return-value="ok">Close</m3e-dialog-action></m3e-button>
  </div>
</m3e-dialog>

Use the m3e-dialog-trigger to open a dialog. This component should be nested inside a clickable element and be associated with a dialog by setting the for attribute to the id of the dialog to open.

When its parent is clicked, it opens the dialog. When the dialog is closed, focus is stored to the parenting element.

Alternately, you can programmatically open a dialog using the show method.

<m3e-button variant="filled">
  <m3e-dialog-trigger for="dlg">Open Dialog</m3e-dialog-trigger>
</m3e-button>
<m3e-dialog id="dlg" dismissible>
  <!-- Content omitted for brevity -->
</m3e-dialog>

When closed, the m3e-dialog emits a closed event. Actions are used to designate a return value, set on the dialog when closed. Use the m3e-dialog-action component define an action.

When the parenting element of a m3e-dialog-action is clicked, it sets the returnValue property of its parenting m3e-dialog to the value of the return-value attribute and closes the dialog.

Alternately, you can programmatically close a dialog using the hide method.

<m3e-button>
    <m3e-dialog-action return-value="ok">Close</m3e-dialog-action>
</m3e-button>

By default, a close (or dismiss) button is not presented for a dialog. Use the dismissible attribute of the m3e-dialog to control this behavior. You can change the icon using the close-icon slot and change the accessible label using the close-label attribute.

The component provides an accessible experience by allowing users to click a dialog's backdrop or press ESCAPE to close a dialog. When this occurs, the cancel event is emitted. Use the disable-close attribute of the m3e-dialog to disable this behavior.

The component provides an accessible experience by providing a focus trap used to keep focus within a dialog. Use the no-focus-trap attribute of the m3e-dialog to disable this behavior.

In addition, you can use the autofocus attribute to specify which action should be focused when the dialog is opened.

The m3e-dialog presents an internal dialog element labelled by the content of the header slot. You can use the alert attribute to specify whether the ARIA role="alertdialog" is applied to the internal dialog.

Dialog triggers add aria-haspopup="dialog" to its parenting element indicating to assistive technologies that activating the control will open a dialog.

This package uses JavaScript Modules. To use it directly in a browser without a bundler, use a module script similar to the following.

<script type="module" src="/node_modules/@m3e/dialog/dist/index.js"></script>

You also need a module script for @m3e/icon-button due to being a dependency.

<script type="module" src="/node_modules/@m3e/icon-button/dist/index.js"></script>

In addition, you must use an import map to include additional dependencies.

<script type="importmap">
  {
    "imports": {
      "lit": "https://cdn.jsdelivr.net/npm/lit@3.3.0/+esm",
      "@m3e/core": "/node_modules/@m3e/core/dist/index.js"
    }
  }
</script>

For production, use index.min.js for faster load times.

This package includes a Custom Elements Manifest (custom-elements.json), which documents the properties, attributes, slots, events and CSS custom properties of each component.

You can explore the API below, or integrate the manifest into your own tooling.