Alert

The Alert component communicates important information to the user: neutral notices, success confirmations, warnings, and critical errors.

Unlike Toasts, Alerts are inline and persistent. They’re built on semantic tokens (bg-card, border-*, text-*) so they remain consistent across themes.

Import

import {
  Alert,
  AlertTitle,
  AlertDescription,
  AlertIndicator,
  AlertContent,
  type AlertProps,
  type AlertVariant,
} from "@pycolors/ui";

Usage

Heads up

This is a neutral message. Use it for non-critical information.

<Alert>
  <AlertTitle>Heads up</AlertTitle>
  <AlertDescription>
    <p>This is a neutral message.</p>
  </AlertDescription>
</Alert>

import { Alert, AlertTitle, AlertDescription } from "@pycolors/ui";

export default function Demo() {
  return (
    <Alert>
      <AlertTitle>Heads up</AlertTitle>
      <AlertDescription>
        <p>This is a neutral message.</p>
      </AlertDescription>
    </Alert>
  );
}

Variants

Variants reflect the semantic meaning of the message. In PyColors UI, variants are mostly expressed through border emphasis and (optionally) indicator color.

Info

Useful context for the user.

Success

Your changes were saved.

Warning

Something may need attention.

Error

We couldn’t save your changes. Try again.

<Alert variant="info">...</Alert>
<Alert variant="success">...</Alert>
<Alert variant="warning">...</Alert>
<Alert variant="destructive" ariaLive="assertive">...</Alert>

import { Alert, AlertTitle, AlertDescription } from "@pycolors/ui";

export default function AlertVariants() {
  return (
    <div className="grid gap-4">
      <Alert variant="info">
        <AlertTitle>Info</AlertTitle>
        <AlertDescription><p>Useful context for the user.</p></AlertDescription>
      </Alert>

      <Alert variant="success">
        <AlertTitle>Success</AlertTitle>
        <AlertDescription><p>Your changes were saved.</p></AlertDescription>
      </Alert>

      <Alert variant="warning">
        <AlertTitle>Warning</AlertTitle>
        <AlertDescription><p>Something may need attention.</p></AlertDescription>
      </Alert>

      <Alert variant="destructive" ariaLive="assertive">
        <AlertTitle>Error</AlertTitle>
        <AlertDescription><p>We couldn’t save your changes. Try again.</p></AlertDescription>
      </Alert>
    </div>
  );
}

Available variants

Variant	Purpose
`default`	Neutral information
`info`	Neutral information (alias of default)
`success`	Confirmation / positive feedback
`warning`	Risk / attention required
`destructive`	Error / critical message

Note: default and info intentionally share the same visual style in the current v1 token set.

Announcements (ariaLive)

PyColors UI includes an ariaLive prop that controls how assistive tech announces updates:

polite (default) → non-blocking updates (role="status")
assertive → critical errors (role="alert")
off → no announcement

Status

Saved in the background (polite).

Critical

Payment failed. Please retry (assertive).

Silent

No live announcement for this message.

<Alert ariaLive="polite">...</Alert>
<Alert ariaLive="assertive">...</Alert>
<Alert ariaLive="off">...</Alert>

import { Alert, AlertTitle, AlertDescription } from "@pycolors/ui";

export default function AlertAriaLive() {
  return (
    <div className="grid gap-4">
      <Alert ariaLive="polite">
        <AlertTitle>Status</AlertTitle>
        <AlertDescription><p>Saved in the background.</p></AlertDescription>
      </Alert>

      <Alert variant="destructive" ariaLive="assertive">
        <AlertTitle>Critical</AlertTitle>
        <AlertDescription><p>Payment failed. Please retry.</p></AlertDescription>
      </Alert>

      <Alert ariaLive="off">
        <AlertTitle>Silent</AlertTitle>
        <AlertDescription><p>No announcement for this message.</p></AlertDescription>
      </Alert>
    </div>
  );
}

With indicator (icon)

Use AlertIndicator + AlertContent to align content. The indicator is positioned absolutely; AlertContent adds left padding so the text lines up.

Check your input

Some fields might be incomplete. Review before submitting.

<Alert variant="warning">
  <AlertIndicator aria-hidden="true">...</AlertIndicator>
  <AlertContent>
    <AlertTitle>...</AlertTitle>
    <AlertDescription><p>...</p></AlertDescription>
  </AlertContent>
</Alert>

import {
  Alert,
  AlertIndicator,
  AlertContent,
  AlertTitle,
  AlertDescription,
} from "@pycolors/ui";

export default function AlertWithIcon() {
  return (
    <Alert variant="warning">
      <AlertIndicator aria-hidden="true">{/* icon */}</AlertIndicator>
      <AlertContent>
        <AlertTitle>Check your input</AlertTitle>
        <AlertDescription><p>Review before submitting.</p></AlertDescription>
      </AlertContent>
    </Alert>
  );
}

API

Props

Prop	Type	Default	Description
`variant`	`AlertVariant`	`"default"`	Visual semantics
`ariaLive`	`"off" \| "polite" \| "assertive"`	`"polite"`	Assistive announcement behavior
`className`	`string`	—	Tailwind override

The Alert components extend standard HTML props:

React.HTMLAttributes<HTMLDivElement>

TypeScript types

Aligned with the source implementation:

export type AlertVariant = NonNullable<AlertProps["variant"]>;

export interface AlertProps
  extends React.HTMLAttributes<HTMLDivElement>,
    VariantProps<typeof alertVariants> {
  ariaLive?: "off" | "polite" | "assertive";
}

Accessibility

ariaLive="polite" renders role="status" (recommended for non-blocking updates).
ariaLive="assertive" renders role="alert" (use for critical errors only).
ariaLive="off" removes live-region announcements (and role).
When using AlertIndicator, mark purely decorative icons with aria-hidden="true".

Design guidelines

Keep alerts short and actionable.
Prefer success only after a user action completes.
Prefer warning when the user can still proceed but should be aware.
Use destructive for errors that block completion.
Don’t overuse assertive alerts; they can be disruptive for screen reader users.