import { Meta, ArgTypes } from '@storybook/blocks'; import { Alert } from './Alert';

Alert

Alert is a fundamental element used for displaying important messages or notifications to users.

About Alert component:

1. When to use
2. Behaviors
3. Types
4. Message type
5. Content
6. Main elements
7. Usage:
   7.1. Inline banner
   7.2. Toast
8. Further Reading

<a name="when-to-use" /> When to use

Use Alerts to inform users of updates, changes, or issues. Providing users feedback, keeping them informed, and keeping disruptions to a minimum is important. There are two different use-cases for Alerts: task-generated and system-generated Alerts.

Task-Generated

Task-generated Alerts are triggered based on the behaviours of the user and provide quick, direct feedback. This type of Alert should be placed closely to the area the user is actively working in.

System-Generated

System-generated Alerts are triggered by the system, unconnected to the actions of a user. Use these Alerts to provide explanation of system status or other events that have occurred elsewhere.

<a name="behaviors" /> 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.

<a name="types"/>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

<a name="message-type"/>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

<a name="content"/>Content

Title

Titles in Alerts are required, always. They should be concise, human-focused and jargon free so users can easily understand them.

Description

Description copy is optional and should be used sparingly. Keep the description copy short and focused on the reason for the Alert and include possible solutions or paths forward to prevent users from being blocked.

Content guidelines (how to write)

It is important to always use simple and concise language when crafting messaging for Alerts. Avoid using jargon or system errors in the content of the Alerts. Provide users with a path forward or possible solution. For more recommendations on writing, view the UX writing guidelines.

Calls to Action

Alerts (Inline Alerts specifically) can contain calls to action (CTAs), especially if there is an action a user can take to remedy or correct the reason the Alert is being shown. When providing a CTA within an Alert be sure to keep the label concise and ensure the action the user can take is clear, and try to keep the labels short (a few words at most). See Grafana's UX Writing guidelines.

<a name="main-elements"/>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.

<a name="usage"/>Usage

<a name="alert-inline" /> 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.
</Alert>

<a name="alert-toast"/>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 + ')'],
});

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>

Further Reading

• NNG -- Indicators, Validations, and Notifications: Pick the Correct Communication Option
• NNG -- How to Report Errors in Forms: 10 Design Guidelines
• NNG -- 10 Usability Heuristics for Users
• NNG -- Plain Language is for Everyone