Alert · Docs · PyColors

UIAlert

Inline feedback for important product statesLink to section

The Alert component communicates important information directly inside the interface.

Use it for:

neutral notices
validation results
success confirmations
warnings
blocking errors
system messages

Unlike Toasts, Alerts are inline and persistent. They remain visible in context until the user understands or resolves the state.

Core idea

Alerts are for messages that belong in the page. Toasts are for temporary feedback.

ImportLink to section

alert-import.tsx

import { Alert } from "@pycolors/ui";

Basic usageLink to section

Use a neutral Alert for non-critical information.

Heads up

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

basic-alert.tsx

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

export function BasicAlert() {
  return (
    <Alert>
      <AlertTitle>Heads up</AlertTitle>
      <AlertDescription>
        This is a neutral message. Use it for non-critical information.
      </AlertDescription>
    </Alert>
  );
}

Typography note

Prefer plain text inside AlertDescription. Avoid nesting extra paragraph tags when the component already renders text semantics.

When to use AlertLink to section

Use Alert when the message should remain visible in context.

Page notice

Explain something important before the user continues.

Success result

Confirm that an important action completed successfully.

Blocking error

Explain what failed and what the user can do next.

VariantsLink to section

Variants reflect the semantic meaning of the message.

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-variants.tsx

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

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

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

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

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

Available variantsLink to section

Variant	Purpose
`default`	Neutral information
`info`	Neutral information, currently aligned with default
`success`	Confirmation or positive feedback
`warning`	Risk or attention required
`destructive`	Error or critical message

Token behavior

default and info intentionally share the same visual language in the current v1 token set.

Announcements with ariaLiveLink to section

The ariaLive prop controls how assistive technologies announce updates.

Value	Role	Use for
`polite`	`status`	Non-blocking updates
`assertive`	`alert`	Critical errors
`off`	none	Static messages that do not need announcement

Status

Saved in the background.

Critical

Payment failed. Please retry.

Silent

No live announcement for this message.

alert-aria-live.tsx

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

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

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

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

Accessibility rule

Use assertive only for urgent errors. Overusing assertive announcements creates a noisy experience for screen reader users.

With indicatorLink to section

Use AlertIndicator with AlertContent when an icon helps reinforce the message.

Check your input

Some fields might be incomplete. Review before submitting.

alert-with-indicator.tsx

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

export function AlertWithIndicator() {
  return (
    <Alert variant="warning">
      <AlertIndicator aria-hidden="true">
        <AlertTriangle className="size-5" />
      </AlertIndicator>

      <AlertContent>
        <AlertTitle>Check your input</AlertTitle>
        <AlertDescription>
          Some fields might be incomplete. Review before submitting.
        </AlertDescription>
      </AlertContent>
    </Alert>
  );
}

Icon rule

If the icon is decorative, add aria-hidden="true". The text must carry the meaning.

Usage patternsLink to section

Use inline alerts for persistent states

Use Alert when the message should remain visible near the relevant content.

Use the variant that matches meaning

Choose success, warning, or destructive only when the message carries that semantic intent.

Keep copy specific and actionable

Explain what happened and what the user can do next.

Announce only what matters

Use polite for status updates and assertive only for critical failures.

Alert vs ToastLink to section

Situation	Use
Blocking page error	Alert
Form-level validation result	Alert
Important persistent notice	Alert
Temporary save confirmation	Toast
Non-blocking background update	Toast
Undo or retry after mutation	Toast

Decision rule

If the user needs the message to complete the task, use Alert. If the message is temporary confirmation, use Toast.

APILink to section

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

Alert components extend standard HTML props:

alert-types.ts

React.HTMLAttributes<HTMLDivElement>

TypeScript typesLink to section