Alert | Calcite Design System

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.

Sample

Usage

Something important was deleted
Confirming an important action
An update is available
Something was saved
Something was downloaded
A problem or error occurred

Component comparison

The Alert, Notice, and Dialog components communicate pertinent information and content to users, but each has its own distinct capabilities and set of use cases.

Alert

This component

Best for ephemeral, workflow specific messaging.

Floats over content to provide timely context without interrupting the workflow.

Most often displayed as a result of user interaction.

Notice

Alternative

Best for informative, contextually relevant information.

Displays within the normal flow of content to highlight or add context.

Can be persisted in the interface or made closable.

Dialog

Alternative

Best for complex or narrative content that contains interactive elements or media.

Floats over content to provide timely context or interactions that interrupt the workflow.

Most often displayed as a result of user interaction.

Accessibility

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`.	`AlertDuration`	`"medium"`
icon	icon	When `true`, shows a default recommended icon. Alternatively, pass a Calcite UI Icon name to display a specific icon.	`IconName \| boolean`
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.	`Extract<"brand" \| "danger" \| "info" \| "success" \| "warning", Kind>`	`"brand"`
labelrequired	label	Specifies an accessible label for the component.	`string`
messageOverrides		Overrides individual strings used by the component.	`Record<string, unknown> \| undefined`
numberingSystem	numbering-system	Specifies the Unicode numeral system used by the component for localization.	`NumberingSystem`
open	open	When `true`, displays and positions the component.	`boolean`	`false`
placement	placement	Specifies the placement of the component.	`MenuPlacement`	`"bottom"`
queue	queue	Specifies the ordering priority of the component when opened.	`AlertQueue`	`"last"`
scale	scale	Specifies the size of the component.	`Scale`	`"m"`
topLayerDisabled	top-layer-disabled	When `true` and the component is `open`, disables top layer placement. Only set this if you need complex z-index control or if top layer placement causes conflicts with third-party components.	`boolean`	`false`

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 component's width.
--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.	bubblescomposed
calciteAlertBeforeOpen	Fires when the component is added to the DOM but not rendered, and before the opening transition begins.	bubblescomposed
calciteAlertClose	Fires when the component is closed and animation is complete.	bubblescomposed
calciteAlertOpen	Fires when the component is open and animation is complete.	bubblescomposed

Methods

Name	Description	Signature
componentOnReady	Creates a promise that resolves once the component is fully loaded.	`componentOnReady(): Promise<this>`
setFocus	Sets focus on the component's "close" button, the first focusable item.	`setFocus(options?: FocusOptions): Promise<void>`