@m3e/snackbar

The @m3e/snackbar package provides the M3eSnackbar global service on window (globalThis) used to present short updates about application processes at the bottom of the screen from anywhere in an application.

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/snackbar

💻 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/snackbar, 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/snackbar/dist/html-custom-data.json"],
  "css.customData": ["./node_modules/@m3e/snackbar/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/snackbar/dist/index.js"></script>

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

<script type="module" src="/node_modules/@m3e/button/dist/index.js"></script>
<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"
    }
  }
</script>

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

🧪 Examples

The following example illustrates basic usage.

M3eSnackbar.open("File deleted");

The next example illustrates presenting a snackbar with an action and callback.

M3eSnackbar.open("File deleted", "Undo", {
  actionCallback: () => {
    // Undo logic here
  },
});

📖 API Reference

🛠️ Snackbar Service

This section details the methods available for the M3eSnackbar service.

⚙️ Methods

| Method | Signature | Description | | --------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | open | open(message: string, options?: SnackbarOptions): void | Opens a snackbar with a message.- message: The message to show in the snackbar.- options: (optional) Options that control the behavior of the snackbar. | | open | open(message: string, action: string, options?: SnackbarOptions): void | Opens a snackbar with a message and action.- message: The message to show in the snackbar.- action: The label for the snackbar action.- options: (optional) Options that control the behavior of the snackbar. | | open | open(message: string, action: string, dismissible: boolean, options?: SnackbarOptions): void | Opens a snackbar with a message, action, and optional close affordance.- message: The message to show in the snackbar.- action: The label for the snackbar action.- dismissible: Whether to present close affordance.- options: (optional) Options that control the behavior of the snackbar. | | open | open(message: string, dismissible: boolean, options?: SnackbarOptions): void | Opens a snackbar with a message and optional close affordance.- message: The message to show in the snackbar.- dismissible: Whether to present close affordance.- options: (optional) Options that control the behavior of the snackbar. | | dismiss | dismiss(): void | Dismisses the currently visible snackbar. |

🗂️ Snackbar

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

⚙️ Attributes

| Attribute | Type | Default | Description | | ------------- | --------- | --------- | ------------------------------------------------------------------------------------------ | | action | string | | The label of the snackbar's action. | | close-label | string | "Close" | The accessible label given to the button used to dismiss the snackbar. | | dismissible | boolean | false | Whether a button is presented that can be used to close the snackbar. | | duration | number | 3000 | The length of time, in milliseconds, to wait before automatically dismissing the snackbar. |

🧩 Slots

| Slot | Description | | ------------ | -------------------------------------- | | (default) | Renders the content of the snackbar. | | close-icon | Renders the icon for the close button. |

🎛️ CSS Custom Properties

| Property | Description | | -------------------------------------------- | -------------------------------------------- | | --m3e-snackbar-margin | Vertical offset from the bottom of viewport. | | --m3e-snackbar-container-shape | Border radius of the snackbar container. | | --m3e-snackbar-container-color | Background color of the snackbar. | | --m3e-snackbar-padding | Internal spacing of the snackbar container. | | --m3e-snackbar-min-width | Minimum width of the snackbar. | | --m3e-snackbar-max-width | Maximum width of the snackbar. | | --m3e-snackbar-supporting-text-font-size | Font size for supporting text. | | --m3e-snackbar-supporting-text-font-weight | Font weight for supporting text. | | --m3e-snackbar-supporting-text-line-height | Line height for supporting text. | | --m3e-snackbar-supporting-text-tracking | Letter spacing for supporting text. | | --m3e-snackbar-supporting-text-color | Color of supporting text. | | --m3e-snackbar-action-text-color | Color of the action button text. | | --m3e-snackbar-close-icon-color | Color of the close icon. |

🤝 Contributing

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

📄 License

This package is licensed under the MIT License.