@m3e/dialog

The m3e-dialog component presents important prompts, alerts, and actions in user flows. Designed according to Material 3 principles, it supports custom header, content, and close icon slots, ARIA accessibility, focus management, and theming via CSS custom properties.

This package is part of M3E monorepo, a unified suite of Material 3 web components. Explore the docs to see them in action.

📦 Installation

npm install @m3e/dialog

💻 Editor Integration

This package includes a Custom Elements Manifest to support enhanced editor tooling and developer experience.

Visual Studio Code

To enable autocomplete and hover documentation for @m3e/dialog, install the Custom Elements Manifest Language Server extension. It will automatically detect the manifest bundled with this package and surface tag names, attributes, slots, and events in supported files.

Alternately, you can explicitly reference the html-custom-data.json and css-custom-data.json in your workspace settings:

{
  "html.customData": ["./node_modules/@m3e/dialog/dist/html-custom-data.json"],
  "css.customData": ["./node_modules/@m3e/dialog/dist/css-custom-data.json"]
}

🚀 Native Module Support

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 it 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/[email protected]/+esm",
      "@m3e/core": "/node_modules/@m3e/core/dist/index.js",
      "@m3e/core/a11y": "/node_modules/@m3e/core/dist/a11y.js"
    }
  }
</script>

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

🗂️ Elements

• m3e-dialog — A Material 3 Expressive dialog for prompts, alerts, and actions.
• m3e-dialog-trigger — An element for opening dialogs by reference (via the for attribute).

🧪 Examples

The following example illustrates a dialog with a header, content, and actions:

<m3e-button variant="filled">
  <m3e-dialog-trigger for="dlg">Open Dialog</m3e-dialog-trigger>
</m3e-button>
<m3e-dialog id="dlg" dismissible onclosed="console.log(this.returnValue)">
  <span slot="header">Dialog Title</span>
  Dialog content goes here.
  <div slot="actions" end>
    <m3e-button autofocus><m3e-dialog-action return-value="ok">Close</m3e-dialog-action></m3e-button>
  </div>
</m3e-dialog>

📖 API Reference

This section details the attributes, slots, events, and CSS custom properties available for the m3e-dialog component.

⚙️ Attributes

| Attribute | Type | Default | Description | | --------------- | --------- | --------- | ------------------------------------------------------------------------------------------- | | alert | boolean | false | Whether the dialog is an alert. | | close-label | string | "Close" | The accessible label given to the button used to dismiss the dialog. | | disable-close | boolean | false | Whether users cannot click the backdrop or press ESC to dismiss the dialog. | | dismissible | boolean | false | Whether a button is presented that can be used to close the dialog. | | no-focus-trap | boolean | false | Whether to disable focus trapping, which keeps keyboard Tab navigation within the dialog. | | open | boolean | false | Whether the dialog is open. |

🧩 Slots

| Slot | Description | | ------------ | ---------------------------------------- | | (default) | Renders the content of the dialog. | | header | Renders the header of the dialog. | | close-icon | Renders the icon of the button to close. | | actions | Renders action buttons for the dialog. |

🔔 Events

| Event | Description | | --------- | ---------------------------------------- | | opening | Emitted when the dialog begins to open. | | opened | Emitted when the dialog has opened. | | cancel | Emitted when the dialog is cancelled. | | closing | Emitted when the dialog begins to close. | | closed | Emitted when the dialog has closed. |

🎛️ CSS Custom Properties

| Property | Description | | ------------------------------------- | ----------------------------------------- | | --m3e-dialog-shape | Border radius of the dialog container. | | --m3e-dialog-min-width | Minimum width of the dialog. | | --m3e-dialog-max-width | Maximum width of the dialog. | | --m3e-dialog-color | Foreground color of the dialog. | | --m3e-dialog-container-color | Background color of the dialog container. | | --m3e-dialog-scrim-color | Color of the scrim (backdrop overlay). | | --m3e-dialog-scrim-opacity | Opacity of the scrim when open. | | --m3e-dialog-header-container-color | Background color of the dialog header. | | --m3e-dialog-header-color | Foreground color of the dialog header. | | --m3e-dialog-header-font-size | Font size for the dialog header. | | --m3e-dialog-header-font-weight | Font weight for the dialog header. | | --m3e-dialog-header-line-height | Line height for the dialog header. | | --m3e-dialog-header-tracking | Letter spacing for the dialog header. | | --m3e-dialog-content-color | Foreground color of the dialog content. | | --m3e-dialog-content-font-size | Font size for the dialog content. | | --m3e-dialog-content-font-weight | Font weight for the dialog content. | | --m3e-dialog-content-line-height | Line height for the dialog content. | | --m3e-dialog-content-tracking | Letter spacing for the dialog content. |

🤝 Contributing

See the root monorepo CONTRIBUTING.md for guidelines on contributing to this package.

📄 License

This package is licensed under the MIT License.