Alert

An alert displays an important message in a way that attracts the user's attention without interrupting the user's task.

---

About Alert component:

1. Behaviors
2. Types
3. Message type
4. Main elements
5. Usage:
   5.1. Inline banner
   5.2. Toast

Behaviors

1. Persistent: They are usually urgent and intrusive, require immediate attention and require action to be dismissed.
2. Passive: Are informational, report a system issue that does not require any action by users.
   

Types

Within Grafana, we have two different types of alerts and they can be used depending on the context and content.

1. Inline banner:
   • To notify users of the status of an action. They appear at the top or bottom of the main content area
   • Passive or Persistent
2. Toast:
   • These temporary window elements are used to display short messages; they appear at the top-right corner of the screen and can be dismissed by clicking the [x] or it will disappear after a few seconds
   • Passive
     

Message Type

1. Informational
   • To provide information to users, and don’t interrupt any current actions
   • Does not require immediate action and can be dismissed by a user clicking the [X] or passively display until the display timer expires
   • Shows blue color on the background and uses the info-circle icon
2. Success
   • To confirm a task is completed as expected or an action is successful.
   • Typically does not require further action and can be dismissed automatically or persist in a nonintrusive manner
   • Shows green color on the background and uses the check icon
3. Warning
   • To inform users that an action is undesirable
   • Often persists until users have taken action to dismiss the notification or taken steps to resolve the issue
   • Shows yellow color on background and uses the exclamation-triangle icon
4. Error
   • To inform that an action hasn't happened as expected, usually something has failed and the user is expected to take action
   • Always persists until the user has taken steps to remedy the issue that triggered the notification
   • Shows red color on background and uses the exclamation-triangle icon
     

Main elements

• Icon status: represents the importance of the message through the color and icon for each status.

• Alert title: should be explicit, clear and short, conveying the most important part of the information.

• Details: precise description for the notification, telling users what they need to do.

• Button and text links: only persistent notifications should contain text links or buttons.

• Close icon: appears when the notification can be dismissed by the user.

  
  

Usage

Inline Banner

Inline Banners are task-oriented alerts that notify users of the status of an action or system. These alerts are contextual — appearing above or below main content areas — allowing users to address issues or to read messages quickly.

Do's

• Use the appropriate status for the message (info/success/warning/error).
• Use plain, simple language for the messages to ensure users understand them and know how to address them.
• Focus on notifications if they are relevant to the users' current workflow and should be addressed immediately.

Don'ts

• Do not use Primary calls to actions.
• Do not hide other content with inline notifications.
• Do not repeat the alert copy/title on the details message.

When to use

• To inform at that time how to continue a task in which users must perform an action.
• To provide some options for users to take action.
• To explain in detail the reasons why something can’t be done by users.

Placement

• Should be placed immediately above or below the related element.

<Alert title={title} severity={severity} buttonContent={buttonContent} onRemove={onRemove}>
  Child content that includes some alert details, like maybe what actually happened.</div>
</Alert>
Copy

Toast

Toast notifications are short messages that appear in the top-right corner of the page and are automatically hidden after a certain amount of time – they provide live notifications, without interrupting the user experience or requiring an action to be taken.

Do's

• Use this component using AppEvents and getAppEvents().
• Show the Toast publishing the appEvent with the proper type and payload needed.

import { AppEvents } from '@grafana/data';
import { getAppEvents } from '@grafana/runtime';

const appEvents = getAppEvents();
appEvents.publish({
  type: AppEvents.alertSuccess.name,
  payload: [text + ': ' + resp.status + ' (' + resp.statusText + ')'],
});
Copy

Don'ts

• Do not use this component directly. Instead, emit the appEvent to trigger it's appearance.

When to use

• To convey general confirmation or non-critical actions.
• Immediately after an event is taken, such as a permission is updated or some Dashboards are imported or deleted.
• Status according to use cases:
  • Success: When any action is successful, it is confirmed when a task is completed as expected.
  • Warning: It is used to report a current status that users should be aware of or that could have serious consequences.
  • Error: Inform users of an error, and sometimes provide more information about how to fix the error.

Placement

• Slide in and out from the top right corner of the page.

<Alert title={title} severity={severity} onRemove={onRemove} elevated>
  Child content that includes some alert details, like maybe what actually happened.
</Alert>
Copy