Alert

v1.1.5

Ready for Production

Catalyst Alert is a compound primitive built from scratch with no upstream dependency. Alert goes with built-in design tokens, CVA variants, and accessibility defaults — giving you a production-ready component with zero configuration.

Installation

npm install @pmi/catalyst-alert

import { AlertRoot, AlertTitle, AlertDescription, AlertDismiss } from "@pmi/catalyst-alert";

Variants

Info

The default variant for general informational messages that do not require immediate attention.

Success

This variant is ideal for confirming successful actions or positive outcomes, such as form submissions or completed tasks.

Warning

Cautionary messages that alert users to potential issues or important considerations but are not critical errors.

Danger

Critical messages that indicate errors, failures, or urgent issues requiring immediate attention.

Common Patterns

Patterns using Icon and action Button are already described in the Variants section.

Controlling Width

The Alert primitive does not expose a size variant. Width is controlled by the w-[700px] base class on AlertRoot. Override this with className to fit your layout.

API

AlertRoot

Extends all standard HTML div element props. The container part. Renders the Alert background, border, and layout.

AlertTitle

Extends all standard HTML div element props. The heading part. Renders a styled title inside the Alert.

AlertDescription

Extends all standard HTML div element props. The body text part. Renders supporting detail below the title.

AlertDismiss

Extends all standard HTML div element props. The dismiss control part. Positioned absolutely at the top-right corner of the alert. Renders with tabIndex={0} for keyboard focus.

Accessibility

Keyboard Interactions

ARIA

• The primitive does not apply ARIA roles or live-region attributes by default. Add them based on the urgency of the alert
• Use role="alert" on AlertRoot for important notifications that should interrupt immediately (equivalent to aria-live="assertive")
  • Avoid using role="alert" for non-critical updates, as frequent interruptions can disrupt screen reader users
• Use aria-live="polite" on AlertRoot for informational updates that can wait for a pause in screen reader output
• Use role="alert" + aria-atomic="true" on AlertRoot for urgent system errors or alerts whose content may change after being announced
  • Use aria-atomic="true" when the entire alert message should be re-announced whenever any portion of its content changes
• Always provide an accessible name using aria-label for AlertDismiss so screen readers announce its purpose
  • Always provide context on what is being dismissed in your aria-label string. For example: "Dismiss payment error alert", "Dismiss account settings alert"

Choosing the Right Component

Use Alert to surface contextual, dismissible feedback tied to a user action or system event — form validation results, save confirmations, permission warnings. Use Alert for inline messaging that appears within the page flow near the relevant content, not as a page-level overlay.

Reach for a different primitive when:

Related

• Banner
• Toast
• Callout