Skip to content

Alerts ​

Overview ​

Alerts provide important prompts within a user flow and are used to ensure users notice and act on critical information. Alerts communicate status, feedback, or required attention without interrupting the user’s task.

Alerts should be used sparingly and consistently to maintain their effectiveness.

Guidelines ​

Dos ​

  • Use alerts to communicate important status updates or required user actions.
  • Place an alert at the top of the content it describes, directly below that content’s heading.
  • Scope the alert to what it affects — the page for page-wide conditions, a panel for a condition confined to that panel.
  • Limit each scope to one (1) alert at a time.
  • Keep alert content to a single line of text whenever possible.
  • Use clear, concise language that communicates the message quickly.
  • Use color to indicate the level of importance or urgency.

Don’ts ​

  • Don’t scope an alert more broadly than the condition it describes — a page-level alert can’t tell the reader which panel is affected.
  • Don’t display more than one alert in the same scope.
  • Don’t place an alert in the middle of its container’s content — it belongs at the top, below the heading.
  • Don’t use alerts for non-critical or decorative messaging.
  • Don’t use multi-line or paragraph-style alert messages.

Content rules ​

Alerts should contain text only, with an optional single hyperlink when necessary.

  • If a link is used, it should provide supporting information or a next step.
  • Keep language concise and actionable.

Placement ​

Alerts are scoped to the content they describe. An alert sits at the top of that content’s container, directly below its heading — the container is the alert’s scope.

ScopeWhere the alert goesUse when
PageTop of the page, directly below the page headerThe condition affects the whole page
ModalTop of the modal body, directly below the modal headerThe condition affects the modal’s task
Panel / sectionTop of the panel’s content, directly below the panel headingThe condition affects only that panel
  • One alert per scope. A page may show more than one alert only when each belongs to a different container — for example a dashboard where two panels independently failed to load. Two alerts in the same scope is never correct.
  • A page-scoped alert and a panel-scoped alert may appear at the same time. They describe different things, so neither suppresses the other.
  • Page-scoped alerts should be immediately visible without scrolling.

Variants ​

VariantDescriptionExample Use
PrimaryHighlights a key message or call to attention using the primary brand colorFeatured announcements, branded prompts
SuccessIndicates successful completion of an action or eventChanges saved, action completed
InfoConveys helpful or relevant information that is not criticalInformational notices
WarningAlerts users to signal potential issues or recommended actionsMissing data, pending actions
ErrorIndicates a critical issue or error has occurredFailed submission, system error

Alerts ​

With icons ​

Panel-scoped alerts ​

Dashboard panels often load their data independently, which means they can fail independently. When a panel can’t load its data, put an Error alert inside that panel, directly below the panel heading, and leave the other panels alone. Knowing which panel failed is the point — the rest of the page is still worth using, and a reader who can’t tell which region is broken can’t judge whether the data they came for is trustworthy.

This is ordinary use of the Error variant, not an exception: the alert is scoped to the panel because the panel is what the condition describes. Several panels failing at once produces several alerts on one page — one per panel — which satisfies the one-alert-per-scope rule above.

Keep the copy to a single line that says what happened, and don’t promise a retry the panel doesn’t offer. A panel that could not load its data reads well as “There was an issue loading this data. The error has been logged for review.”

The same placement applies to a .panel — the alert goes at the top of the .panel-body, below the .panel-heading.

Empty states are a separate matter

An alert says something went wrong. A panel that loaded successfully and simply has nothing to show (“No events to display”) is an empty state, not an error, and must not use an alert. Beacon does not document a panel empty state yet — check with Design rather than reaching for alert-info.