Alerts are contextual pop-up style messages that can contain actions without obstructing the application.
Overview
Alerts are used to communicate to the user in an unobtrusive manner. They are primarily displayed as a response to the user taking action on an element; however they can also be used to communicate non-critical system messages, or to provide updates on actions the user has previously taken.
Try to avoid stacking Alerts. If you find a need to present the user with multiple Alerts at once, or when you want to interrupt the user, please consider using a Dialog.
Refer to the UI state colors if you are unsure of what color Alert to use.
Usage
- Something important was deleted
- Confirming an important action
- An update is available
- Something was saved
- Something was downloaded
- A problem or error occurred
Sample
<calcite-alert icon="rangefinder" kind="brand" open label="A report alert">
<div slot="title">Trail Camera Report </div>
<div slot="message">We thought you might want to take a look</div>
<calcite-link slot="link">Take action</calcite-link>
</calcite-alert>
Best Practices
While visually similar to Notice, Alert has distinct capabilities and intended use cases. It is positioned absolutely over content and may be constrained to the bounds of a parent when slotted.
Comparison
open
at page load.open
at page load, or displayed as a result of user action.closable
.open
at page load for introductory messaging.Recommendations
Alerts are used to communicate to the user in a noticeable but non-interruptive manner. They are primarily displayed as a response to the user taking action on an element; however they can also be used to communicate non-critical system messages, or provide updates on actions the user has previously taken.
Accessibility
Keyboard navigation
Key | Function |
---|---|
Tab | Moves focus to next focusable element. If the current focus is the last element, focus will leave the component. |
Tab and Shift | Moves focus to previous focusable element. If the current focus is the first element, focus will leave the component. |
Writing and copy
Alerts are meant to quickly convey a message to the user. Consistent Alert structure, verbiage, and copy ensures that the user will have an expected experience across the platform. Keep copy short and to the point.
API reference
Properties
Property | Attribute | Description | Type | Default |
---|---|---|---|---|
autoClose | auto-close | When true , the component closes automatically. Recommended for passive, non-blocking alerts. | boolean | false |
autoCloseDuration | auto-close-duration | Specifies the duration before the component automatically closes - only use with autoClose . | "fast" | "medium" | "slow" | "medium" |
icon | icon | When true , shows a default recommended icon. Alternatively,
pass a Calcite UI Icon name to display a specific icon. | boolean | string | |
iconFlipRtl | icon-flip-rtl | When true , the icon will be flipped when the element direction is right-to-left ("rtl" ). | boolean | false |
kind | kind | Specifies the kind of the component, which will apply to top border and icon. | "brand" | "danger" | "info" | "success" | "warning" | "brand" |
label | label | Specifies an accessible name for the component. | string | |
messageOverrides | Use this property to override individual strings used by the component. | { close?: string; } | ||
numberingSystem | numbering-system | Specifies the Unicode numeral system used by the component for localization. | "arab" | "arabext" | "latn" | |
open | open | When true , displays and positions the component. | boolean | false |
placement | placement | Specifies the placement of the component. | "bottom" | "bottom-end" | "bottom-start" | "top" | "top-end" | "top-start" | "bottom" |
queue | queue | Specifies the ordering priority of the component when opened. | "immediate" | "last" | "next" | "last" |
scale | scale | Specifies the size of the component. | "l" | "m" | "s" | "m" |
Slots
Name | Description |
---|---|
title | A slot for adding a title to the component. |
message | A slot for adding main text to the component. |
link | A slot for adding a calcite-action to take from the component such as: "undo", "try again", "link to page", etc. |
actions-end | A slot for adding calcite-action s to the end of the component. It is recommended to use two or fewer actions. |
Styles
Name | Description |
---|---|
--calcite-alert-width | Specifies the width of the component. |
--calcite-alert-background-color | Specifies the component's background color. |
--calcite-alert-corner-radius | Specifies the component's corner radius. |
--calcite-alert-shadow | Specifies the component's shadow. |
--calcite-alert-offset-size | Specifies the component's placement offset. |
Events
Name | Description | Behavior |
---|---|---|
calciteAlertBeforeClose | Fires when the component is requested to be closed and before the closing transition begins. | |
calciteAlertBeforeOpen | Fires when the component is added to the DOM but not rendered, and before the opening transition begins. | |
calciteAlertClose | Fires when the component is closed and animation is complete. | |
calciteAlertOpen | Fires when the component is open and animation is complete. |
Methods
Name | Description | Signature |
---|---|---|
componentOnReady | Create a promise that resolves once component is fully loaded. | componentOnReady(): Promise<void> |
setFocus | Sets focus on the component's "close" button, the first focusable item.
@returns {Promise | setFocus(): Promise<void> |