Alerts

Luke van Zyl·Updated April 6, 2026

Overview

An alert communicates a system or status message to the user. It can be informational, confirmatory, cautionary, or critical depending on the context. Alerts appear inline within a page or panel, and in extreme cases (system outages, global announcements) can be rendered full-width at the top of the layout using the same component.

Sandbox

Specs

Hierarchy

Weight

Title

Title

Description

Description

Anatomy

1. Container — The surface of the alert, colored by severity level.
2. Icon — A leading icon indicating severity; matches the alert's level.
3. Title (optional) — A short, bold summary of the message.
4. Body — The main message text.
5. Action (optional) — A button or link that lets the user respond directly to the alert.
6. Dismiss button (optional) — An × icon button that lets the user close the alert.

Variants

Weight

Weight controls the visual intensity of the alert. Use the weight that matches how much attention the message needs.

Default — Uses a tinted background with a colored icon and title. Use this for most in-page alerts where the message is informational but not critical.

Strong — Uses a fully saturated background with high-contrast foreground. Use this when the message demands immediate attention and needs to stand out from surrounding content.

Severity Level

Severity maps to the category of information being communicated.

Default — A neutral, stone-toned alert used for general informational messages. No urgency. No action required.

Success — Confirms that something went right. Use to close the feedback loop after a user action. Pair with an action or auto-dismiss when appropriate.

Warning — Signals a downstream impact or something that requires the user's attention. In a clinical context, warnings are high-stakes — use them when inaction could have consequences. Include an action whenever possible.

Negative — Indicates an error, a blocked state, or a critical problem. This is the highest severity. Reserve it for situations where something has gone wrong or access has been restricted. Should not be dismissible unless the underlying issue is already resolved.

Global Alert Banner

The global alert banner is a full-width variant of the alert that sits at the very top of the page, above all other content. Use it for system-wide messages where every user on the page needs to be informed: outages, critical announcements, or platform-level warnings.

Because it pushes page content down, the layout shifts to prioritize vertical efficiency:

• Dismiss button moves to the far left
• Message is centered and kept to a single line where possible
• Action button (if present) sits on the far right

The global banner uses the same severity levels, weights, and tokens as the inline alert. MUI doesn't ship a separate banner component — this is the standard Alert rendered at page scope inside a full-width container.

Inline CTA

By default, the CTA renders below the title and description, and the alert can be dismissed. When Inline CTA is enabled, the CTA moves to the right of the content on the same row. The dismiss control is not available in this configuration.

Use Inline CTA when horizontal space is sufficient and you want a compact, banner-style alert — for example, the weight-change warning on the Ax Sheet. Avoid it when the title or description is long enough to wrap, since the layout will feel crowded.

The icon is optional in both configurations via the Show Icon boolean.

Dismissibility

All alerts technically support a dismiss button, but whether to include one is a product decision, not a default. As a general rule: the higher the severity, the less likely the alert should be dismissible. Warning and danger alerts should stay visible until the user has addressed the underlying issue. Success and informational alerts are reasonable candidates for dismissal.

Usage

Alerts appear wherever the system needs to communicate status, feedback, or a required action to the user.

• Dose Review Required — On the Tx Sheet, a warning alert appears when a patient's weight has changed and calculated medication quantities may no longer be accurate. It includes a direct action ("Review Doses") to route the user to the right place.
• Scheduling Restricted — In the New Appointment pane, a warning alert blocks scheduling when an account has been flagged due to unpaid invoices. It surfaces the reason and links to the account so staff can act.
• Global alert banners — For system-wide messages (outages, critical announcements), use the global alert banner variant. It renders full-width at the top of the layout with a horizontal layout optimized for minimal vertical height. See the Global Alert Banner variant above.

When not to use: Don't use an alert for routine status updates that don't require attention or action. If the information is passive and won't affect the user's workflow, it belongs in a status indicator, not an alert.

Best Practices

Do	Don't
Include an action in warning and danger alerts so users know how to resolve the issue	Don't show a warning or danger alert without telling the user what caused it
Match the severity level to the actual impact — use warning and danger sparingly	Don't use danger for messages that are merely informational
Keep alert body copy short and direct	Don't use alerts to show success for every minor interaction
Allow success and informational alerts to be dismissible	Don't make a warning or danger alert dismissible unless the issue is already resolved
Use the strong weight in dense layouts where the alert might otherwise get lost	Don't stack multiple alerts of the same severity when one consolidated message would do

Accessibility

• Use role="alert" for dynamic alerts injected after page load so screen readers announce them immediately.
• Use role="status" for lower-priority messages (e.g., success confirmations) that don't need to interrupt the user.
• The severity icon is decorative if the severity is also communicated in the alert text. If the icon is the only severity indicator, give it an aria-label.
• The dismiss button must have an accessible label: aria-label="Dismiss alert". An × character alone is not sufficient.
• Don't rely on color alone to convey severity. Each level must be differentiated by icon and text as well.
• Keyboard: Tab moves focus to any interactive elements inside the alert (action button, dismiss). Enter or Space activates them.