Usage
A toast is a brief, self-dismissing message that confirms an action or reports status. A Toast Group anchors and stacks the toasts on the page; individual Toast elements live inside it.
Import the parts you need — each import registers its custom element:
import "@nordhealth/components/lib/Toast"
import "@nordhealth/components/lib/ToastGroup"
Place a single Toast Group near the root of your app, then add toasts to it:
In code you'll usually add toasts imperatively rather than rendering them in markup:
const group = document.querySelector("nord-toast-group")
group.addToast("Message sent")
group.addToast("No internet connection", { variant: "danger" })
Composition
A Toast Group is the container that positions and stacks the toasts it holds.
ToastGroup
├── Toast
└── Toast
<nord-toast-group>
<nord-toast>Message sent</nord-toast>
</nord-toast-group>
Toast Group
Toast Group anchors the toasts in a fixed region and stacks them. Render one per app. Its addToast(message, options) method is the usual way to show a toast.
Toast
Toast is a single message. Use variant to convey status and auto-dismiss to control how long it stays (in milliseconds) before dismissing itself.
Examples
Variants
Use variant to signal the nature of the message.
Custom auto-dismiss
Override how long a toast stays before dismissing itself with auto-dismiss (milliseconds).
Error
Use the error variant for failures that the user needs to notice and act on.
RTL
Toasts follow the document or container direction. Toggle the direction to see the layout mirror.
Accessibility
- The Toast Group is a live region, so toasts are announced to screen reader users as they appear.
- Keep messages short and specific. Use
variantto reinforce meaning, but don't rely on colour alone — the message text should stand on its own. - Don't put essential, time-consuming actions in a toast that dismisses itself; use a Banner or Notification for persistent messages.
API reference
Toast
Toasts are non-disruptive messages that appear in the interface to provide quick, at-a-glance feedback on the outcome of an action.
<nord-toast></nord-toast>Props
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
variant | variant | The style variant of the toast. | 'default' | 'danger' | 'default' |
autoDismiss | auto-dismiss | Timeout in milliseconds before the toast is automatically dismissed. | number | 10000 |
Slots
| Slot name | Description |
|---|---|
Default slot | Default slot used for the toast text/message. |
| Event | Detail Type | Description |
|---|---|---|
dismiss | NordEvent | Fired when the toast is dismissed (via user action or auto-dismiss), and its exit animation has completed. This event should be used to remove the dismissed toast from the DOM. |
Parts
This component is made up of the following parts.
Toast Group
Toast group is used to position and style a group of toasts, whilst ensuring they are announced by screen readers.
<nord-toast-group></nord-toast-group>Slots
| Slot name | Description |
|---|---|
Default slot | Default slot in which to place toasts. |
| Event | Detail Type | Description |
|---|---|---|
dismiss | NordEvent | Fired when a toast is dismissed (via user action or auto-dismiss), and its exit animation has completed. This event should be used to remove the dismissed toast from the DOM. |
Dependencies
This component is internally dependent on the following components:
Design guidelinesFor designers
Usage
This section includes guidelines for designers and developers about the usage of this component in different contexts.
Do
- Use for short messages that confirm an action taken by a user.
- Use for ephemeral status updates.
- Use in combination with Toast group so that toasts get styled and announced to screen readers correctly.
Don’t
- Don’t use toasts for critical information that user needs to act on. Consider using a Notification instead.
- Don’t rely on users seeing toasts. Toasts are transient and should not be used for critical messages.
- Don’t place interactive content in toasts. Assistive technology like screen readers will not convey any semantics when announcing toast messages.
- Don’t use for error messages unless absolutely necessary. Try to favor a Banner for error messaging instead.
Content guidelines
Toast content should be clear, accurate and easy to understand:
When writing the toast content, use the {noun} + {verb} content formula:
Use a maximum of 3 words when writing the toast content:
When writing the toast content, always write it in sentence case, not title case. The first word should be capitalized and the rest lowercase (unless a proper noun):
Avoid unnecessary words and articles in the toast content, such as “the”, “an” or “a”:
Never end in punctuation:
Additional considerations
- Toasts are complicated from an accessibility perspective. Whilst they are a convenient UI pattern for messaging, they present difficulties for keyboard or screen reader users. Therefore careful consideration should be given as to whether a toast is the correct choice.
- If the message cannot be conveyed in 3 words or less, consider re-wording. If the message cannot be shortened any further, consider choosing a different pattern than toast.