Alert

Semantic Variants

Visual Variants

Structural Variants

Size Variants

Alert Properties

Design Token Mappings

Use the Color Palette Generator to generate consistent semantic color scales for all four variants.

Alert States

Contextual States

Dynamic Alerts

Alerts that appear dynamically (after an API call, form submission, or system event) should be announced to screen readers. This is where role="alert" or role="status" becomes critical:

• role="alert": Assertive. Screen readers interrupt whatever they're reading to announce the alert. Use for errors and urgent warnings.
• role="status": Polite. Screen readers announce it after finishing the current sentence. Use for success messages and informational updates.
• Neither: For alerts that are present on page load (not dynamically inserted), no ARIA role is needed — the user will encounter them naturally while reading.

WCAG Requirements

ARIA Implementation

For dynamically injected alerts:

<!-- Error: assertive announcement -->
<div role="alert">
  <strong>Error:</strong> Unable to save your changes. Please try again.
</div>

<!-- Success: polite announcement -->
<div role="status">
  Your profile has been updated successfully.
</div>

For alerts present on page load:

<!-- No role needed — content is in the natural reading flow -->
<div class="alert alert-info">
  <p>This feature is currently in beta.</p>
</div>

Dismissible Alert Accessibility

• The dismiss button must have aria-label="Dismiss" or aria-label="Close alert"
• After dismissal, focus should move to a logical location (the next element in the flow, or the preceding heading)
• The dismissal should be announced: inject a visually-hidden "Alert dismissed" text in an aria-live region

Color Contrast Per Variant

This is the biggest accessibility pitfall with alerts. Typical failures:

Always test every variant in both light and dark mode. The Contrast Checker supports both.

For comprehensive patterns, see our WCAG Practical Guide and ARIA Attributes Guide.

Do's

• ✅ Use the correct semantic variant. Don't use a warning alert for an error, or an info alert for a success message. The color and icon should match the meaning.
• ✅ Lead with the most important information. "Your account has been suspended" first, explanation second.
• ✅ Include an action when possible. "Your session expires in 5 minutes. [Extend session]" is more useful than just the warning.
• ✅ Use alert as a form error summary. At the top of the form, show "There are 3 errors below" with links to each field. This is especially valuable for long forms.
• ✅ Keep alert text concise. One sentence for the title, 1–2 sentences for the description. If you need more, link to a detail page.
• ✅ Make page-level error alerts persistent until the error is resolved. Don't auto-dismiss errors.

Don'ts

• ❌ Don't stack more than 2–3 alerts at once. If you have that many, consolidate or redesign the page state.
• ❌ Don't use alerts for marketing. "New feature! Check it out!" is a banner, not an alert. Alerts are for status and feedback.
• ❌ Don't auto-dismiss error alerts. The user needs time to read, understand, and act. Success alerts can auto-dismiss; errors should not.
• ❌ Don't place alerts at the bottom of the page where users might not see them. Position them near the relevant content (top of the form, inside the affected section).
• ❌ Don't use an alert where a Toast would suffice. If it's brief feedback that doesn't require action ("Copied to clipboard"), a Toast is less intrusive.
• ❌ Don't use colored text on colored backgrounds without checking contrast. This is the #1 accessibility failure in alert components. Validate every color combination with the Contrast Checker.

Content Guidelines

• Title: Short, descriptive, not alarming ("Payment method expiring" not "URGENT: PAYMENT ISSUE!!!")
• Description: Explain the situation and what the user can do about it
• Action labels: Verb-first, specific ("Update payment method", "View details", "Try again")
• Error lists: Link each error to the corresponding field: "Email address is required" → clicking scrolls to and focuses the email field

Cross-System Comparison

Notable Approaches

Ant Design Alert is the most complete implementation. It supports all four semantic variants with automatic icons, a banner mode that stretches full-width with no border-radius (for page-level announcements), a closable prop with afterClose callback, and a description prop that separates the title from the body. It also supports a message array for showing multiple messages in one alert.

Shadcn/ui keeps alerts minimal — just default and destructive variants, styled with Tailwind. This is intentional: they treat alerts as styled containers and expect you to compose the content (icons, titles, descriptions, actions) manually. It's flexible but requires more work for each usage.

Material 3 doesn't have a direct "Alert" component — Material philosophy prefers Snackbars (transient) for feedback and Banners (persistent, full-width) for status messages. If you need a classic inline alert in a Material system, you compose it from a Card or custom component.

Radix has no alert primitive because alerts are purely presentational containers with ARIA attributes — there's no complex interaction behavior to abstract. The ARIA part (role="alert", role="status") is trivial to add to a styled <div>.

Bootstrap's Alert deserves a mention for its influence: it established the four-color (info/success/warning/danger) convention that virtually every design system has adopted. The pattern is so universal that users now intuitively understand blue = info, green = success, yellow = warning, red = error without any labels.

For accessible color palettes that work across all four variants in both light and dark mode, use our Color Palette Generator to generate consistent scales.