JM Family Design System

Alert

Alerts communicate important feedback, warnings, validation outcomes, and status changes. They should be direct, recoverable, and used only when the message needs attention.

Guidance for adoption

Start here before choosing examples or props. These notes explain where Alert helps, where another pattern is better, and what should stay true in product work.

When to use

  • Inline feedback
  • Validation summaries
  • System notices
  • Recoverable warnings

When not to use

  • Decorative callouts
  • Replacing field-level errors
  • Routine page copy
  • Marketing emphasis

Accessibility expectations

  • Use role="status" for non-urgent updates and role="alert" for urgent errors.
  • Keep alert text concise enough to be announced clearly.
  • Move focus to critical blocking alerts after submit.

Content guidance

  • Write a direct title that names what happened or what needs attention.
  • Keep the message short and recovery-oriented so users understand the next step.
  • Choose severity by user impact, not by how strongly the message should stand out visually.
  • Use plain, specific error copy instead of vague phrases like "Something went wrong".

Implementation notes

  • Use live="alert" for urgent blocking errors and status behavior for non-urgent updates.
  • Use field-level errors for single field problems and an Alert for summaries or broader workflow impact.
  • Render recovery buttons or links inside children; there is no dedicated action slot.
  • Do not use Alert for routine page copy, marketing emphasis, or decorative callouts.

Import

import { Alert } from '@/components/ui/Alert';

Severities map to icon, color, and ARIA live region. Errors use role="alert"; the rest use status.

Severity

Severity should map to user impact. The color, icon, title, and message all work together so the alert is understandable without relying on color alone.

Info
New vendor fields available

Use the new tax classification field for requests submitted after May 31.

Use for neutral context users should notice.

Success
Vendor request submitted

The approval workflow has started and the requester was notified.

Use for completed actions or positive confirmation.

Warning
Approval may be delayed

Missing insurance documents can slow down review by Procurement.

Use when users can prevent or prepare for a problem.

Error
Request could not be submitted

Fix the highlighted fields and submit the request again.

Use for blocking failures, validation summaries, or failed actions.

Usage patterns

Alerts work best when they are close to the affected workflow and written as a short explanation with a clear next step.

Inline notice
Review policy updates

New contract thresholds apply to requests over $50,000.

Place near the related content so the message has context.

Validation summary

Use after submit when multiple fields need attention.

Recoverable warning
Documents expire soon

Request updated insurance before the renewal review.

Explain the risk and the next step without sounding like a failure.

Success confirmation
Changes saved

The vendor profile now reflects your updates.

Confirm what happened and what users can expect next.

Anatomy

Alerts need a semantic role, a visible severity cue, a direct title, and enough detail for the user to understand what changed or what to do next.

  1. Severity icon
  2. Direct title
  3. Recovery-oriented message
  4. Optional action
  5. Live region role
  6. Related placement

Props

The component accepts every native HTMLDivElement attribute on top of the design system props below.

PropTypeDefaultDescription
severity'info' | 'success' | 'warning' | 'error''info'Semantic level. Maps to icon, color, and default ARIA role.
titleReactNode—Bold heading rendered before the body message.
iconReactNode—Override the default severity icon. Pass null to hide it.
live'alert' | 'status'—Sets the ARIA live region role. Use "alert" for errors that need immediate attention.

Usage rules

Choose severity by user impact

Severity should reflect the consequence and urgency, not the desire to make a message stand out.

Do not use alerts as decoration

If the message is routine page copy or marketing emphasis, use normal content structure instead.

Give users a next step

When something needs attention, explain what happened and how to recover.

Do not replace field errors

Use field-level errors for specific input problems; use an alert to summarize or explain form-level impact.

Known limitations

What Alert does not do yet, and what consumers need to compose themselves.

  • No dismiss control. The component renders a static region with no close button, onDismiss callback, or auto-dismiss timer; transient toast-style alerts must be composed externally.
  • No action slot. There is no action prop for an inline button or link, so recovery CTAs must be rendered inside children and styled by the consumer.

Related anti-patterns

Catalog entries to watch for when using Alert. Read these before shipping; they describe the failure modes the system has already documented.

Agent guidance

Agents should use alerts when feedback changes what users need to know or do. They should not turn ordinary explanatory content into alert styling.

Generation rules

  • Choose severity by user impact, not visual emphasis.
  • Write a direct title and a short recovery-oriented message.
  • Use field-level errors for single field problems and an alert for form-level summaries.
  • Do not rely on color alone; pair severity with icon, heading, and text.
  • Use an Alert, not a toast, for any failure the user must act on. Auto-dismissing transient messages for blocking errors matches the toast-for-critical-errors anti-pattern.
  • Write copy that names the failure and the next step in plain language. Whimsical phrasing such as "Oops" or "Something went sideways" matches the cute-error-messages anti-pattern.
  • For recovery CTAs, render a Button or Link inside the alert children. There is no action slot prop, so the consumer styles spacing and order.
  • Pair the severity variant with the matching icon and a textual cue such as "Error:" or "Success:". Communicating severity through color alone matches the color-only-state anti-pattern.

Baseline example

import { Alert } from '@/components/ui/Alert';

<Alert severity="error" title="Request could not be submitted" live="alert">
  Fix the highlighted fields and submit the request again.
</Alert>
If generated UI needs a critical alert, the agent should also generate the recovery path: field errors, next-step copy, or a clear action.

Decision standard

Use an alert when users need to notice a state change, warning, validation result, or system message. If nothing changes what the user needs to do, use normal content.