The message-card element

Overview

The <message-card> element provides functions and formatting for messages to be displayed in the DOM. It can function as embedded messaging, that is always displayed, or dynamic, notification-like messaging that is added and removed from the DOM.

Along with those use cases, the <message-card> element is designed to be "opened" and "closed", similar to a <dialog> element, so that a static message may be hidden and re-used. This allows common use-cases like error messages to be statically defined in the HTML, while also providing the ability to include messages with dynamic, contextual content at runtime.

Basic Examples

The <message-card> element includes a variety of customization. In the simplest example, an empty message card, with a header of "Message" can be displayed by adding a <message-card> element with an open attribute.

From there, any child content of the <message-card> element, that is not assigned a slot property, will be added as the card's message content.

For convenience, if the card's content is only text, that can also be added to the <message-card> element by setting its value attribute's value to the message.

Similar to the value, the <message-card> element's header can be set either in the child content — by using the heading slot — or by setting the text of the heading attribute.

The <message-card> element can be "closed" by clicking the close button. Closing the element removes the open attribute, which sets the display to none by default.

While themeing this element is entirely customizeable by using css properties (variables), it provides default themes to easily distinguish between common message types. By setting the <message-card> element's type attribute to one of the pre-defined types, the element will take on a simple style to indicate that intention.

The examples below demonstrate the customization options, as well as each of the supported message card types.

Customize the heading with slot the "heading" slot

Dynamic Message Cards

The <message-card> element provides the notify() and prepare() functions for dynamically managing messages. These functions automatically handle establishing a timeout for the message, showing progress for that timeout, and removing the element from the DOM when the timeout has completed.

Timeouts are managed by the <message-card> element's duration attribute. Any value above zero will be used as the milliseconds for the notification to be displayed before being removed. This may be done directly in the HTML, but the prepare() and notify() functions manage those timeouts, directly.

Timeout progress is tracked by the progress bar along the bottom of th <message-card> element. When the element has focus, or is being hovered over, the progress will be paused.

The prepare() function is used to add a <message-card> element to a parent element. It requires a message parameter and the parent element that it will append the message to as a parameter. It can also accept an options parameter for defining things like the <message-card> element's duration, heading, and type.

The notify() function provides a convenient way to prepare a <message-card> element and open it at the same time.

To make it easier to use customized <message-card> elements, the notify() and prepare() functions can accept a <message-card> element as their first parameter, rather than a message string. The same events and functionality will apply to the provided <message-card> element. The only difference will be that the custom-defined <message-card> element will be used, rather than simply injecting a message into the default <message-card> element structure.

In this example, each button will add a new <message-card> element to the DOM.

  • Custom

Events

The <message-card> element dispatches events to indicate automatic manipulation and manual interaction. The open and close events are dispatched whenever the open attribute is toggled. When a <message-card> element is removed from the DOM, the remove event is dispatched. The cancel event indicates that the close button was selected by a user, and the progresscomplete event is dispatched after a <message-card> element's duration has elapsed and the progress value reaches zero.

In this example, there is a single static message that can be opened or closed with the buttons, and another button that will add <message-card> elements to the DOM, dynamically. Each of the <message-card> element's events are logged below.

This card is static and will not be removed automatically from the DOM. Clicking the "X" will "close" the element, which will set its display to none, by default. But the element will still be present in the DOM and can be displayed, again, by adding an "open" attribute.
Log