Skip to content
Nexus Application Design nadesign

Alert

An <Alert> is an inline, persistent message scoped to a region. It tells the user something about that region — never about something happening elsewhere on the page.

import from "@na/ui/components/alert" ▶ Open in Storybook packages/ui/src/components/alert.tsx

When to use

  • Inline guidance at the top of a form (“This action will email all subscribers”).
  • A persistent warning inside a section (“This integration is in beta”).
  • A system-state banner inside a card (“Your trial ends in 3 days”).

Don’t use for transient notifications. Action-result feedback (saved, deleted, failed) is a Toast (Sonner). Modal confirmations are AlertDialog. Form-field errors are FormError — never an Alert.

Default

<Alert>
  <IconInfoCircle />
  <AlertTitle>Heads up</AlertTitle>
  <AlertDescription>
    This integration is in beta. We may change behavior without notice.
  </AlertDescription>
</Alert>

Destructive

<Alert variant="destructive">
  <IconAlertCircle />
  <AlertTitle>Run failed</AlertTitle>
  <AlertDescription>
    Tool <code>search_kb</code> returned a 500. Trace: <code>req_x9k2</code>.
  </AlertDescription>
</Alert>

Without icon

The icon is optional. Skip when the parent surface (a section header, a labeled fieldset) already names the topic.

<Alert>
  <AlertTitle>Saved drafts</AlertTitle>
  <AlertDescription>We auto-save every 30 seconds. You can leave and come back without losing changes.</AlertDescription>
</Alert>

With action

Inline an action when the user can act on the alert directly. Don’t make the action the only way to dismiss — alerts should remain useful as ambient information.

<Alert>
  <IconAlertTriangle />
  <AlertTitle>Trial ends in 3 days</AlertTitle>
  <AlertDescription>
    Add a payment method to keep your workspace active.
    <span className="mt-2 inline-flex">
      <Button size="sm">Add payment method</Button>
    </span>
  </AlertDescription>
</Alert>

API

Alert

Prop Type Default Description
variant "default" | "destructive" "default" Visual + semantic variant.
className string — Forwarded.
...rest HTMLAttributes<HTMLDivElement> — All native div attributes. role="alert" is always set.

AlertTitle

Prop Type Default Description
className string — Forwarded.
...rest HTMLAttributes<HTMLDivElement> — All native div attributes.

AlertDescription

Prop Type Default Description
className string — Forwarded.
...rest HTMLAttributes<HTMLDivElement> — All native div attributes.

Design guidelines

✓ Do

  • Place Alerts at the top of the region they describe — not the top of the page.
  • Lead with the noun. "Run failed" not "There was a failure with the run".
  • Pair AlertTitle + AlertDescription. A title alone reads like a label; a description alone has no anchor.

✗ Don't

  • Use Alert for transient feedback. Saves, deletes, and failures should toast (Sonner).
  • Use destructive variant for warnings that are not errors. The system has only one red.
  • Stack two Alerts. If you need two messages, you need to design the surface differently.

Accessibility

  • Root has role="alert" set automatically — screen readers announce when the Alert mounts.
  • For Alerts that may update in place (countdown, retry status), set aria-live="polite" on the parent region — role="alert" is aria-live="assertive" and shouldn’t fire repeatedly.
  • Color is never the only signal — destructive variant pairs with explicit text and (recommended) an icon.

▶ Open Alert stories in Storybook