Alert

v1.0.0 | View in Storybook

​

When to use

• For contextual guidance or inline recommendations: When users need clarification or additional context about their current task or when suggesting next steps within the workflow.

Example: Displaying an Alert within a symbols or mapping list to help explain how a user can link or unlink assets.

• To communicate warnings or issues: When an action requires attention, but isn’t blocking progress or the user can resolve the issue in a separate context.

Example: Alerting the user that transformations have failed and user action is required to troubleshoot the problem.

• When actions need to be taken: If the user should resolve an issue directly within the Alert.

Example: Re-establishing a failed connection.

​

When to use something else

• When the message is critical and must be acknowledged: Use a Dialog instead to capture user attention.
• For system-wide notifications or alerts: Use a Sonner, Banner, or the notification center.
• For immediate feedback such as success or failure of an operation when the user does not need to be given a lot of details: Use a Sonner and allow them to try again.
• When the errors prevent the user from continuing such as “page not found”, “no access” or server error: Use a full page Empty state.
• If the information is not tied to a specific user action or context: Use Tooltips or inline text for passive guidance.
• If a form field requires validation: Use inline validation messages provided with Combobox, Input, Select, or Textarea.

​

Dos and don’ts

• Do use action Buttons when the action is specific to the message and will resolve (dismiss) it.
• Do consider other methods for feedback before using an Alert, such as inline validation on forms. Avoid mixing multiple feedback states as this becomes confusing or frustrating to a user.
• Do use the correct status type depending on the alert. If none exists, use a neutral or info type.
• Do place Alerts near the content they relate to and set the width.
• Do use a strip style Alert if the content must span the full page.
• Don’t use action Buttons for unrelated activities or activities that don’t resolve the Alert.

​

Placement

• Always align the edge of the Alert relative to the surrounding content. Alerts should never be flush to a container’s divider.
• Use the card style Alert when content needs to wrap and applies to a small container.
• Use the strip style Alert when content is short and applies to a larger container.

​

Behavior

• Inline to the page: it does not block the full viewport like a Dialog or Alert dialog.
• Dismissal removes the alert from the layout (or hides it) per variant; optional actions should complete or dismiss the alert in one clear step.
• If the alert includes focusable controls, manage focus appropriately; otherwise it typically does not trap focus.
• Product rules decide whether dismissed state persists across navigation or sessions.

​

Often used with

Button for dismiss or fix-it actions; optional inline icon; sits above related content, not inside unrelated Card chrome unless scoped to that region.

​

Accessibility

• ARIA roles: Use role="alert" (assertive) for urgent visual notifications requiring immediate user attention, and role="status" (polite) for routine status changes.
• Color redundancy: Never rely on color alone (e.g., green/red fills) to distinguish success from error states—always pair with explicit icons and text prefixes like “Error:” or “Success:”.
• Contrast: Maintain a minimum text-to-background contrast ratio of 4.5:1 for light and dark variant alerts.

​

Visual examples

The examples below are interactive and follow the doc site’s theming: light mode when the docs site is in light mode, and dark mode when you switch the docs site to dark mode.

​

Dismissible

Use a dismissible Alert when the message is informational or resolved by the user, and they should be able to close it manually without taking further action.

​

Secondary

Use the secondary Alert variant for lower-emphasis guidance that supplements the main content without drawing as much attention as info, warning, or error styles.

​

Neutral card type

Use the neutral card-type Alert when context applies to a smaller container and the message may wrap across multiple lines—for example, within a card or narrow panel.

​

Info strip type

Use the info strip-type Alert for short, inline messages that span a wider container, such as contextual tips above a data table or form section.

​

Warning

Use a warning Alert when an action or state requires attention but does not block progress—for example, a failed background job that the user can troubleshoot later.

​

Error alert

Use an error Alert when something has failed and the user must take action or acknowledge the problem before continuing—for example, a connection failure that blocks the current task.

​

All variants

Reference this example to compare all Alert visual variants side by side when choosing the appropriate emphasis, layout, and semantic color for a given message.

​

Description only

Use a description-only Alert when a short message is sufficient and a title would add unnecessary redundancy—for example, a single-line clarification within a workflow.

​

Custom icon

Use a custom icon in an Alert when the default semantic icon does not match the message context, but keep icon usage consistent with the alert’s intent.

​

Multiple actions

Use multiple action buttons in an Alert when the user has more than one valid way to resolve the issue—for example, “Retry” and “View details”—and limit choices to avoid decision overload.

​

Controlled visibility

Use controlled visibility when the Alert’s open or closed state must follow application logic—for example, reopening after a failed save attempt or syncing with parent state.

​

Edge case long text

Test long text in Alerts to ensure titles and descriptions wrap correctly within card and strip layouts without breaking alignment or truncating critical information.

​

Edge case special characters

Verify that Alerts render special characters and unicode correctly in titles and descriptions, especially when displaying dynamic user-generated or localized content.

​

Edge case no icon

Use an Alert without an icon when the message is neutral or when visual noise should be minimized, but ensure the text alone conveys severity clearly.

​

Edge case no icon with close

Combine a no-icon Alert with a close control when the message is low emphasis and users should be able to dismiss it without a primary action button.