Alert usage guidelines

Alerts are messaging banners that appear inline with the page content, typically in response to system updates like form validation.

When to use

• For inline validation and feedback, like errors within forms or specific sections of a page.
• To communicate status updates or warnings related to a particular element or section.
• To display page-wide updates or feedback that are important and need to be read and addressed by a user.

When not to use

• Use an alert dialog for messages that are urgent or require immediate user action or input.
• Use a toast for low-importance feedback messages that do not need to be addressed by the user.
• Use callout for proactive, general announcements or updates that are not triggered by a specific user action.

Alerts vs. callouts
Alerts and callouts are similar concepts that often get confused:

• Alerts are used in response to a user action. They cannot contain interactive elements. Screen readers will announce the contents of every alert whenever it is rendered or updated. Alerts should therefore be used sparingly, and only for high priority feedback.
• Callouts are used to call the user’s attention to information within the page flow. They can contain interactive elements. Screen readers treat callouts as normal text in the page flow.

Properties

Tone

Preview

Info

This is an info alert.

Success

This is a success alert.

Warning

This is a warning alert.

Critical

This is a critical alert.

Code

import { Alert, Stack } from '@cimpress-ui/react';

export default function Demo() {
  return (
    <Stack gap={16}>
      <Alert tone="info" title="Info">
        This is an info alert.
      </Alert>
      <Alert tone="success" title="Success">
        This is a success alert.
      </Alert>
      <Alert tone="warning" title="Warning">
        This is a warning alert.
      </Alert>
      <Alert tone="critical" title="Critical">
        This is a critical alert.
      </Alert>
    </Stack>
  );
}

Caution

Tone is a visual-only concept. Screen readers won’t convey the tone of the alert.

Value	Use cases
Info	Used for important details without implying positivity or negativity.
Success	Used for confirmation of successful actions, processes, and positive outcomes.
Warning	Used for non-critical issues, potential problems that won’t block user progress, and recommendations for attention.
Critical	Used for critical issues that will block user progress or otherwise need to be addressed.

Formatting and layout

Placement

Alerts should be placed directly above the content they pertain to and as close to the relevant content as possible. They are inline elements and should not overlap other elements.

Content writing

• Do be specific about the update, issue, or status. Use language that the user can understand.
• For errors and warnings, do give users a path to resolving the issue and explain any consequences of not doing so.
• Do not use jargon or technical terms that are unfamiliar to users.

Behaviors

Non-interactive

Alert is a static (non-interactive) element. It only conveys information, and doesn’t provide any actions.

Dismissing alerts

By default, alerts cannot be dismissed by the user. A close icon (“X”) can be added to the alert to allow users to dismiss it. This should not be added to alerts informing users of critical, blocking errors or actions the user needs to take to resolve the issue, because once alerts are dismissed users can no longer access that information.