Alert
On this page
Importing
Add rh-alert to your page with this import statement:
<script type="module">
import '@rhds/elements/rh-alert/rh-alert.js';
</script>
Copy to Clipboard
Copied!
Wrap lines
Overflow lines
To learn more about installing RHDS elements on your site using an import map read our getting started docs.
Usage
<rh-alert>
<h3 slot="header">Default</h3>
<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam eleifend elit sed est
egestas, a sollicitudin mauris tincidunt.</p>
<rh-button slot="actions" variant="secondary" data-action="confirm">Confirm</rh-button>
<rh-button slot="actions" variant="link" data-action="dismiss">Cancel</rh-button>
</rh-alert>
<script type="module">
import '@rhds/elements/rh-alert/rh-alert.js';
import '@rhds/elements/rh-button/rh-button.js';
</script>
Copy to Clipboard
Copied!
Wrap lines
Overflow lines
Toasting Alerts
The toast variant of alert is intended specifically and only to be used when
toasting alerts. To toast an alert, use the static toast() method on the
RhAlert constructor. Avoid writing your own
<rh-alert variant="toast"> in HTML. The argument to toast() is an object
with at least a message property, and several other options.
import { RhAlert } from '@rhds/elements/rh-alert/rh-alert.js';
RhAlert.toast({ state: 'success', message: 'Saved!' });
The full list of options for the toast method is:
| Option | Type | Description |
|---|---|---|
message (required) |
lit-html renderable value | Alert body content. Can be any value which lit-html can render. Simple strings are preferable |
heading |
string |
Alert heading content. Must be a simple string. |
state |
See alert's state attribute |
Alert state attribute |
persistent |
boolean |
Whether the alert should remain on screen until the user explicitly dismisses it |
actions |
Array of one or two actions objects | One or more optional body actions. See actions options info below. |
Toast action options
Actions objects have two keys, text for the action button text, and action
e.g. dismiss or confirm, which is applied to the close event as the
action property.
| Option | type | Description |
|---|---|---|
text |
string | Button label text, e.g. "Confirm" |
action |
string | close event event.action property e.g. 'confirm' |
Toasted alert content
When toasting, you must provide body content for the alert. This content can
either be a string, a DOM node, a lit-html TemplateResult, or an array of the
same.
Toasting a string
await RhAlert.toast({
message: 'Your request was submitted',
});
Toasting a DOM Node
const message = document.createElement('strong');
message.textContent = 'Your request was submitted';
await RhAlert.toast({ message });
Toasting a lit-html template:
import { html } from 'lit';
await RhAlert.toast({
message: html`Your request was <em>submitted</em>`,
});
Toasting an array of renderables
import { html } from 'lit';
await RhAlert.toast({
message: [
'Your request was',
html`<em>successfully</em>`,
new Text('submitted'),
],
});
You may, for example, use the <template> element to define alert content
<template id="success-alert-content-template">
<p>Your subscription has been successfully renewed.</p>
<p>Contact <a href="#">Customer support</a> for more information.</p>
</template>
const template = document.getElementById('success-alert-content-template')
const { childNodes } = template.content.cloneNode(true);
const message = Array.from(childNodes);
await RhAlert.toast({ message });
Alert headings
You can provide an optional string for the alert's heading, which will
become the text content of the alert's slotted heading (h3).
import { RhAlert } from '@rhds/elements/rh-alert/rh-alert.js';
await RhAlert.toast({
state: 'success',
heading: 'Subscription renewed',
message: 'Your subscription was successfully renewed',
});
Persistent toasted alerts
Toasted alerts can be timed or persistent. Timed alerts remain on screen for
eight seconds before disappearing. Persistent alerts remain on screen until the
user explicitly dismisses them. To make your toasted alert persistent, use the
persistent: true option.
import { html } from 'lit';
await RhAlert.toast({
state: 'warning',
persistent: true,
message: html`Your subscription will expire in <time>two days</time>`,
});
Toasted alert actions
Like inline alerts, toasted alerts may include one or two actions. When there are two actions, the first will be a secondary variant button, and the second a link variant button. If there is only one action, it will be a link button.
Responding to actions
Actions have a button text and an action string, which identifies which button
was pressed. You can listen for the close event, and if it is an
AlertCloseEvent object, it will have an action property.
import { AlertCloseEvent } from '@rhds/elements/rh-alert/rh-alert.js';
document.addEventListener('close', function(event) {
if (event instanceof AlertCloseEvent) {
switch (event.action) {
case 'renew':
// renew subscription
break;
}
}
});
await RhAlert({
state: 'warning',
message: 'Your subscription is about to expire',
actions: [
{ text: 'Renew', action: 'renew' },
{ text: 'Dismiss', action: 'dismiss' },
]
});
By default, clicking on an action button will remove the alert. If you would like to keep the alert on screen, prevent the default action:
document.addEventListener('close', function(event) {
if (event instanceof AlertCloseEvent) {
switch (event.action) {
case 'prevent':
// prevent alert from closing
event.preventDefault();
// ... do something with event
break;
}
}
});
rh-alert
An alert provides a banner for status changes or messages.
It uses ARIA role="alert" so screen readers must announce
its content. Authors should provide a heading and must avoid
nesting alerts. Users may Tab to interactive elements and
press Enter to activate them. Meets WCAG 2.4.3.
Slots
3
| Slot Name | Summary | Description |
|---|---|---|
actions
|
Up to two |
|
header
|
Alert heading; must be a heading element
(e.g. |
|
[default]
|
Body content for the alert; accepts block
elements like |
Attributes
3
| Attribute | DOM Property | Description | Type | Default |
|---|---|---|---|---|
state
|
state |
Communicates the urgency of a message and is denoted by various styling configurations.
Note: 'note', 'default', and 'error' will also work, but are deprecated |
|
|
variant
|
variant |
The alternate Inline alert style includes a border instead of a line which can be used to express more urgency or better grab the attention of a user. A Toast alert is used to present a global message about an event, update, or confirmation, like the result of a user action that cannot be presented within a specific layout or component. |
|
|
dismissable
|
dismissable |
Alert variants have different rules regarding their ability to be dismissed by a user. Default, Info, and Success Inline alerts can be dismissed by a user selecting the close button. Warning and Danger Inline alerts can be dismissed by a user resolving the issues caused by the alert. All Toast alerts can be dismissed by a user selecting the close button or waiting for them to time out. |
|
|
Methods
0
None
Events
1
| Event Name | Description |
|---|---|
close
|
Fires when dismissed via
close button or action click. |
CSS Shadow Parts
0
None
CSS Custom Properties
0
None
Design Tokens
38
| Token | Description | Copy |
|---|---|---|
--rh-space-xl
|
Action button inline end margin 24px spacer |
|
--rh-color-interactive-primary-default
|
Action link color |
|
--rh-color-interactive-primary-hover
|
Action link hover/focus color |
|
--rh-color-teal-10
|
Default surface color Alert - Default background |
|
--rh-color-teal-50
|
Default border color Default icon color Alert - Default accent |
|
--rh-border-width-md
|
Alert border width 2px border width: Example: Alert |
|
--rh-color-surface-dark
|
Alert dark mode surface color Tertiary surface (dark theme) |
|
--rh-space-lg
|
Footer block start margin Alert padding 16px spacer |
|
--rh-font-weight-body-text-regular
|
Alert font weight Regular font weight |
|
--rh-font-family-body-text
|
Alert font family Header font family Body text font family |
|
--rh-font-weight-body-text-medium
|
Header font weight Medium font weight |
|
--rh-line-height-body-text
|
Alert line height Header line height Line height for body text |
|
--rh-font-size-body-text-sm
|
Action button font size Alert font size Header font size Description font size 14px font size |
|
--rh-color-status-neutral
|
Neutral state border color |
|
--rh-color-icon-status-neutral
|
Neutral state icon color |
|
--rh-color-surface-status-neutral
|
Neutral state surface color |
|
--rh-color-status-info
|
Info state border color |
|
--rh-color-icon-status-info
|
Info state icon color |
|
--rh-color-surface-status-info
|
Info state surface color |
|
--rh-color-status-success
|
Success state border color |
|
--rh-color-icon-status-success
|
Success state icon color |
|
--rh-color-surface-status-success
|
Success state surface color |
|
--rh-color-status-caution
|
Caution state border color |
|
--rh-color-icon-status-caution
|
Caution state icon color |
|
--rh-color-surface-status-caution
|
Caution state surface color |
|
--rh-color-status-warning
|
Warning state border color |
|
--rh-color-icon-status-warning
|
Warning state icon color |
|
--rh-color-surface-status-warning
|
Warning state surface color |
|
--rh-color-status-danger
|
Danger state border color |
|
--rh-color-icon-status-danger
|
Danger state icon color |
|
--rh-color-surface-status-danger
|
Danger state surface color |
|
--rh-color-surface-lightest
|
Toast surface color Primary surface (light theme) |
|
--rh-box-shadow-xl
|
Toast box shadow Extra large box shadow |
|
--rh-space-xs
|
Header block end margin Grid gap Heading block end padding Close button area inline end margin 4px spacer |
|
--rh-size-icon-02
|
Status icon inline size Status icon block size 24px icon box |
|
--rh-color-text-secondary
|
Close button color |
|
--rh-length-xl
|
Close button block size Close button inline size 24px length token |
|
--rh-color-text-primary
|
Header text color Close button hover color |
|
Other libraries
To learn more about our other libraries, visit this page.
Feedback
To give feedback about anything on this page, contact us.