Alert

Installation

The component is exported from @by/experience-system. Add the package with your package manager:

pnpm add @by/experience-system

In this monorepo, depend on the workspace package (for example via workspace:* or your catalog) so imports resolve to packages/experience-system.

Composition

Use the following composition to build an Alert:

Alert
├── AlertTitle
├── AlertDescription
└── AlertAction

AlertAction is optional—omit that branch when you do not need controls in the top-end corner. Optionally add a single leading icon from @by/icons as a direct child of Alert (typically an SVG component before AlertTitle); the root grid places the icon in the first column when present.

Usage

import { Alert, AlertDescription, AlertTitle } from '@by/experience-system';

Alert is a client component ('use client'). Use it inside a Client Component or a dynamic import when using the Next.js App Router.

<Alert>
  <AlertTitle>Heads up</AlertTitle>
  <AlertDescription>You can add a description and next steps here.</AlertDescription>
</Alert>

Examples

Basic

A default alert with a leading icon, title, and description. The live preview at the top of this page uses the same example (alert-basic).

Error

Use color="error" for failures the user must address.

Info

Use color="info" for informational callouts.

Success

Use color="success" for confirmations and positive outcomes.

Warning

Use color="warning" for caution or time-sensitive notices.

With action

Use AlertAction for a control in the top-end corner (for example Retry).

In card

Place alerts inside Card for notifications or grouped system messages.

API Reference

Subsection titles name the exports from @by/experience-system. These parts are plain React components (not Radix primitives); props follow the tables below.

Alert

Root callout container. Renders a div with role="alert" (the role prop is not customizable).

Also accepts standard div attributes except role (it is always alert).

AlertTitle

Title or heading row. Renders a div.

Also accepts standard div attributes.

AlertDescription

Body copy; supports paragraphs and rich text. Renders a div.

Also accepts standard div attributes.

AlertAction

Optional actions (for example buttons), aligned to the end of the first row. Renders a div.

Also accepts standard div attributes.

Accessibility

• Use role="alert" sparingly so assistive technologies do not announce noise.
• Keep AlertTitle and AlertDescription together for a clear hierarchy.
• Decorative icons should use aria-hidden; meaningful icons need an accessible name.
• Ensure controls inside AlertAction are keyboard-focusable and have visible labels.

Source in the repo: packages/experience-system/src/components/Alert/Alert.tsx and variants.ts. Agent-oriented usage notes: packages/experience-system/src/components/Alert/Alert.instructions.md.