import { Alert } from '@uhg-abyss/web/ui/Alert';<Alert title="Alert" status="success"> Lorem ipsum odor amet, consectetuer adipiscing elit. Ipsum rhoncus duis vestibulum fringilla mollis.</Alert>Title
Use the title prop to set the title of the Alert. A title is not required. By default, the title is rendered as an <h2>, but this can be configured using the headingLevel prop.
Content
The children of the Alert will be displayed as the main content. The content can only be a string and is limited to 100 characters in length.
Status
Use the status prop to change the style of the Alert. The available options are 'error', 'info', 'success', and 'warning'. The default value is 'error'.
CTA
Use the cta prop to add a call to action to the Alert. The cta prop accepts an object of the following type:
{ type: 'button' | 'link', props: ButtonProps | LinkProps,}ButtonProps and LinkProps are objects that accept most props of the Button and Link components, respectively, except for size, which is set by the Alert and cannot be altered.
Programmatically displaying alerts
Use the isVisible prop to control whether the Alert is displayed. The default value is true.
Dismissible
Use the dismissible prop to control whether the Alert can be closed manually. The default value is true. This prop must be used in conjunction with isVisible and onClose to work properly.
onClose
Use the onClose prop to execute a custom callback when the Alert is closed.
Note: onClose is only executed when the close button is clicked (i.e., when dismissible is true). It is not executed when the Alert is closed programmatically.
Show divider
Use the showDivider prop to control whether a divider is shown before the close button. The default value is true. This prop is only used when dismissible is true.
Note: Since the inline variant does not use a divider, this prop has no effect when inline is true.
Timestamp
Use the timestamp prop to display a timestamp below the content of the Alert.
Note: This example uses the Day.js library to format the timestamp, but you're free to use any method you like. We recommend using Day.js, though, as it is easy to use, very readable, and already included with Abyss. Timestamps can automatically be formatted based on the user's locale using the LocalizedFormat plugin.
Inline
Use the inline prop to display Alert as an inline element instead of as a banner. The default value is false.
Accessibility
Use the ariaText prop to provide additional information denoted by the color/status. This will be announced before visible text. For more information, visit the Accessibility tab.
Responsiveness
On screens less than 744px wide, the Alert will adjust its layout. Resize the window to see the change!
Alert Props
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
ariaLive | "assertive" | "polite" | "off" | - | - | Overrides the default aria-live attribute for the Alert, which is 'polite' if status is 'success' or 'info' and is not present if status is 'error' or 'warning' |
ariaText | string | - | - | Extra text for accessibility purposes; read before the title |
children | string | - | The contents of the Alert | |
className | string | - | - | CSS class name to apply to each element within the component |
css | Abyss.CSSProperties | Partial<Record<`abyss-${T}`, Abyss.CSSProperties>> | - | - | Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation |
cta | { type: "button"; props: AlertButton; } | { type: "link"; props: AlertLink; } | - | - | If present, the Alert will display a button or a link |
data-testid | string | - | - | Suffix used to create a unique ID used for automated testing |
describedById | string | - | - | An id to associate the Alert body text with for aria-describedby |
disableDefaultProviderProps | boolean | false | - | If set to true, the component will not use the DefaultPropsProvider values. If you aren’t using the DefaultPropsProvider, this prop can be ignored. |
dismissible | boolean | true | - | If true, the Alert can be dismissed |
headingLevel | 1 | 2 | 3 | 4 | 5 | 6 | 2 | - | The heading level of the Alert title |
inline | boolean | false | - | If true, the Alert will be displayed as an inline element |
isVisible | boolean | true | - | If true, the Alert will be visible |
onClose | React.MouseEventHandler<HTMLButtonElement> | - | - | Callback function executed when the Alert is closed; only used when dismissible is true |
showDivider | boolean | true | - | If true, the Alert will show a divider before the close button; Only used when dismissible is true |
status | "error" | "info" | "warning" | "success" | 'error' | - | The status of the Alert |
timestamp | string | - | - | If present, the Alert will display a timestamp |
title | string | - | - | The title of the Alert |
Alert Classes
| Class Name | Description |
|---|---|
| .abyss-alert-live-region | Alert aria-live region wrapper element |
| .abyss-alert-root | Alert root element |
| .abyss-alert-wrapper | Alert wrapper element |
| .abyss-alert-icon | Alert icon element |
| .abyss-alert-content | Alert main content container |
| .abyss-alert-timestamp-container | Alert timestamp container |
| .abyss-alert-close-button-container | Alert close button container |
| .abyss-alert-text-container | Alert text content container |
| .abyss-alert-title-container | Alert title container |
| .abyss-alert-title | Alert title element |
| .abyss-alert-body-text | Alert body text element |
| .abyss-alert-timestamp | Alert timestamp element |
| .abyss-alert-cta-container | Alert CTA container |
| .abyss-alert-cta-button | Alert CTA button element |
| .abyss-alert-cta-link | Alert CTA link element |
| .abyss-alert-separator | Alert separator element |
| .abyss-alert-close-button | Alert secondary button element |
| .abyss-alert-close-icon | Alert close button icon element |
An alert is an element that displays a brief, important message in a way that attracts the user's attention without interrupting the user's task. Dynamically rendered alerts are automatically announced by most screen readers, and in some operating systems, they may trigger an alert sound. It is important to note that, at this time, screen readers do not inform users of alerts that are present on the page before the page load completes.
Adheres to the WAI-ARIA Alert design pattern.
The Alert Example provided by W3.org demonstrates the Alert Pattern.
Keyboard Interactions
| Key | Description |
|---|---|
| Tab | Moves focus on the next interactive element within the Alert |
| Shift + Tab | Moves focus to the previous interactive element within the Alert |
| Enter | When focus is on a button within the Alert, pressing enter will press the button |
| Space | When focus is on a button within the Alert, pressing space will press the button |
Decorative Icons
The brand icon in the Emphasis Banner is considered decorative and does not require a text alternative, though one can be provided if desired.
Close Button Guidance
If the close button is present—which it is by default—it must be keyboard accessible. A keyboard-only user must be able to tab to the button and activate it with the space bar and the enter key. When the Alert is closed, focus must be placed back where it previously was on the page.
ARIA Properties
If status is 'success' or 'info', Alert has the following ARIA properties:
role="status"aria-live="polite"
If status is 'warning' or 'error', Alert has the following ARIA properties:
role="alert"
BrAT Variant Behaviors
-
JAWS
- Only announces text
- Does not announce actions or close button
-
NVDA, VoiceOver
- Both announce all contents, though not roles (link, button)
Common issue: Immediate announcements require adding alerts to page AFTER loading
For an Alert to announce immediately, they must be added AFTER the page content is loaded. This makes them a dynamic update to the page.
The examples here display them on page load. This makes them more like static banners.
Announcing "Alert" (or "Warning", etc.) - Defining alt text for icons
Even in those cases, they will not announce as "Alerts" unless alt text is defined for the icon. Otherwise, only the displayed text will be announced.
Use the ariaText prop to define this text.
Component Tokens
Note: Click on the token row to copy the token to your clipboard.
Alert Tokens
| Token Name | Value | |
|---|---|---|
| alert.color.border.container.error | #E8C0C0 | |
| alert.color.border.container.info | #C3D8F2 | |
| alert.color.border.container.success | #BFDBBF | |
| alert.color.border.container.warning | #F3D8C0 | |
| alert.color.border.separator | #4B4D4F | |
| alert.color.icon.content.error | #990000 | |
| alert.color.icon.content.info | #126ECF | |
| alert.color.icon.content.success | #007000 | |
| alert.color.icon.content.warning | #C24E14 | |
| alert.color.icon.utility.active | #000000 | |
| alert.color.icon.utility.hover | #323334 | |
| alert.color.icon.utility.rest | #4B4D4F | |
| alert.color.surface.container.error | #FCF0F0 | |
| alert.color.surface.container.info | #EEF4FF | |
| alert.color.surface.container.success | #F0F9ED | |
| alert.color.surface.container.warning | #FFFBEB | |
| alert.color.text.heading | #323334 | |
| alert.color.text.paragraph | #4B4D4F | |
| alert.color.text.timestamp | #4B4D4F | |
| alert.border-radius.all.container.inline | 8px | |
| alert.border-width.all.container.inline | 1px | |
| alert.border-width.bottom.container.banner | 1px | |
| alert.border-width.separator | 1px | |
| alert.sizing.all.icon.content.banner | 24px | |
| alert.sizing.all.icon.content.inline | 20px | |
| alert.sizing.all.icon.utility | 20px | |
| alert.spacing.gap.horizontal.container.mobile | 16px | |
| alert.spacing.gap.horizontal.container.inline | 8px | |
| alert.spacing.gap.horizontal.container.web | 24px | |
| alert.spacing.gap.horizontal.wrapper.web | 24px | |
| alert.spacing.gap.horizontal.text | 16px | |
| alert.spacing.gap.vertical.content.inline | 8px | |
| alert.spacing.gap.vertical.content.mobile | 8px | |
| alert.spacing.gap.vertical.content.web | 8px | |
| alert.spacing.gap.vertical.text | 4px | |
| alert.spacing.padding.all.container.inline | 16px | |
| alert.spacing.padding.all.container.mobile | 16px | |
| alert.spacing.padding.horizontal.container.web | 24px | |
| alert.spacing.padding.vertical.container.web | 16px |