Alert

An Alert is a “conversation” between the system and the user. It is prompted when the system needs input from the user or to give the user urgent information concerning their current workflow.

Alerts work best when used for short tasks or to warn the user to task relevant information. Alerts are useful in many scenarios; they are less disorientating than navigating a user to a new page for simple tasks or knowledge gathering. However, Alerts are disruptive and can be distracting to the user. Use them sparingly.

Anatomy

Structure

<Alert> <Heading /> /* (Required) The heading of the Alert */ <Content /> /* (Required) The content of the Alert */ </Alert>

Composed Components

A Alert uses the following components:

Usage

Default

An alert must have a heading, some content and a primary button label.

Secondary button

An alert can have a secondary button.

Cancel button

An alert can have a cancel button.

Disabled buttons

An alert primary and secondary buttons can be disabled.

Confirmation

Use a confirmation alert when a non-destructive action is required from a user.

Destructive

Use a destructive alert to confirm a permanent change, like deleting data.

Not Dismissable

An alert can be undismissable.

Controlled

The open state can be handled in controlled mode.

Pending

An alert can show a pending state. This is useful when you want to show that an action is in progress.

Sizes

A Alert can be small or medium. The default size is medium.

Responsive sizes

A Alert can have different size in mobile and desktop view.

Best Practices

Use alerts sparingly

Don't overuse alerts. They are disruptive and can easily annoy the user if used incorrectly or too frequently. When alerts are used for non-workflow related tasks, it is likely a user will start ignoring or dismissing the alert without fully understanding the content. This can cause users to make hurried or impulsive choices when dealing with more critical alerts.

Alerts should be user initiated

A user action, such as clicking a button, should trigger the alert to open. Don't interrupt the user by opening an alert when they aren't expecting it. Avoid system generated pop-ups that distract the user while working. Triggers can either be a direct or indirect consequence of a user's action. An example of an indirect action is a user closing a tab with unsaved content that then causes an alert to ask if they want to save their changes before closing. If the system is autogenerating an alert that is not a consequence of a user's action, but a response to processes happening in the background, then a toast notification should be used instead.

Keep alert tasks simple and focused

Alert tasks should be direct and easy to complete. Avoid feature creep in alerts where a once simple alert has become bloated with interactions. When deciding to use an alert consider how the task could expand in the future and if an alert will be able to effectively incorporate additions.

Dismissing an alert

  • Task completion: clicking the primary action will complete the task and automatically close the alert
  • Cancel button: clicking the Cancel button will close the modal and return the user to its previous context. Cancel undoes all applied changes.
  • X: Clicking the Dismiss button at the upper right will close the alert without submitting any data and return the user to its previous context.
  • Esc: Press ESC on the keyboard.

Props

Alert

autoFocusButton?

The button to focus by default when the alert open.

cancelButtonLabel?

The cancel button label.

isDismissable?

Whether or not the dialog should close on outside interactions.

Defaults to true.
primaryButtonDisabled?

Whether or not the primary button is disabled.

primaryButtonLabel

The primary button label.

secondaryButtonDisabled?

Whether or not the secondary button is disabled.

secondaryButtonLabel?

The secondary button label.

variant?

The visual style of the Alert.

Defaults to confirmation.
size?

The size of the Alert.

Defaults to md.
overlayProps?

Additional props to render on the wrapper element.

isLoading?

Whether or not the Alert is loading.

style?

The inline style for the element.

children?

Children of the dialog. A function may be provided to access a function to close the dialog.

className?

The CSS className for the element.

AlertTrigger

isOpen?

Whether the overlay is open by default (controlled).

defaultOpen?

Whether the overlay is open by default (uncontrolled).

Migration Notes

Coming from Orbiter, you should be aware of the following changes:

  • dismissable has been renamed isDismissable.
  • wrapperProps has been renamed overlayProps.
  • onClose has been removed.