Skip to main content
Alert - Demos
Toggle Light/Dark ThemeView GitHubToggle right to left

#Alert

This package exports an extremely nice component for showing alerts if you are able to only use the React context API to queue up these alerts named MessageQueue. As the name suggests, this is a queue of messages (toasts) to display to the user in a Snackbar that has built in accessibility so that new messages will be read out to screen readers.

To use this functionality, you'll normally want to mount the MessageQueue component near the root of your app and then use the addMessage function provided by the useAddMessage hook. Whenever the addMessage is called, a message will be pushed onto the queue and automatically shown to the user for 5 seconds before automatically hiding and triggering the next message if one exists. However, if the browser window loses focus while the message is displayed, the timeout will be stopped and restarted once focus is returned so that messages aren't accidentally lost or not shown.

The autohide functionality is configurable to be different times or completely disabled on a per-message basis.

#Simple Message Queue

This example will be fairly simple and show some example messages you can send using the addMessage API. The messages are fairly customizable out of the box and it can render:

  • a single line of text
  • two lines of text
  • an optional action button
  • two lines of text stacked above an action button
  • any renderable content

The basic requirements for a message is to contain a children property that will be used as the main text within the Toast. This should normally be a short string, but it can be any renderable React node as well. Here's a quick example:

1234addMessage({ children: "This is an example message" });
addMessage({
  children: <span className="custom-style">This is another message</span>,
});

When you want to add an action button to the message, you can provide a new property named action. This should either be a string, a renderable React node, or an object of button props. The action button will be defaulted to:

  • gain the "flat" style
  • gain the "secondary" theme color
  • have an id of actionProps.id, ${toastId}-toast, ${toastId}-toast, or undefined if none of the preceding ids are available
  • immediately hiding the toast when clicked
Show CodeOpen Code SandboxView source GitHub

#Handling Duplicated Messages

If the example above you might have noticed that if you spammed the "Add Message" button, the same toast would be shown repeatedly by hiding and reappearing. This is the default behavior out of the box but it can be updated so that duplicates will be prevented entirely or that the timer will be restarted if the same message is added to the queue while it is currently visible.

Note: Updating the behavior to "restart" will also prevent duplicates from being added even if the current message is not being shown.

When you change this behavior, you'll need to start adding a messageId property to each message to uniquely identify each message. This works great if you are using an internationalization library since you can just use the message keys as a unique identifier. Otherwise, you can just create an enum of message ids or a record of messages to display and reference those instead.

Show CodeOpen Code SandboxView source GitHub
MessageQueue duplicate behavior

#Updating Message Priority

Whenever you call the addMessage the new message will be added to the end of the queue. This is great for most use cases, but what about important notifications that need to be shown immediately such as online/offline status? When you create a message, you can also add a messagePriority property that will update the message's insertion point in the queue. The default behavior is to always add the new message at the end of the queue, but there is also support for:

  • "normal" - the default behavior or adding the message to the end of the queue
  • "next" - the message will be shown immediately if there are no messages in the queue or will be shifted to the next position in the queue so it will be shown once the current message is dismissed or auto-hidden.
  • "immediate" - triggers the exit animation for the current message (if there is one) and shows this message instead. When this message is hidden, the previous message will be shown again
  • "replace" - immediately swaps out the current message with the new one while restarting the display timer. The previous message will never appear again unless triggered manually
Show CodeOpen Code SandboxView source GitHub
Message queue:
Priority