# Alert

import { Callout } from "fumadocs-ui/components/callout";
import { Accordion, Accordions } from "fumadocs-ui/components/accordion";
import { Step, Steps } from "fumadocs-ui/components/steps";
import { Tabs, Tab } from "fumadocs-ui/components/tabs";
import {
  Badge,
  Card,
  CardContent,
  CardHeader,
  CardTitle,
} from "@pycolors/ui";
import {
  Accessibility,
  AlertTriangle,
  ArrowRight,
  BellRing,
  CheckCircle,
  CircleAlert,
  Info,
  Megaphone,
  Palette,
  ShieldAlert,
  XCircle,
} from "lucide-react";
import { PreferAvoid } from '@/components/docs/prefer-avoid';
import { DocsLinks } from "@/components/docs/docs-links";
import { DocsFeatureGrid } from "@/components/docs/docs-feature-grid";

<div className="flex flex-wrap items-center gap-2">
  <Badge variant="outline">
    UI
  </Badge>

  <Badge>
    Alert
  </Badge>
</div>

## Inline feedback for important product states

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.

<Callout title="Core idea">
  Alerts are for messages that belong in the page. Toasts are for temporary feedback.
</Callout>

### Import

```tsx title="alert-import.tsx"
import { Alert } from "@pycolors/ui";
```

### Basic usage

Use a neutral Alert for non-critical information.

<Tabs items={["Preview", "Code"]}>
  <Tab value="Preview">
    <Preview>
      <Alert className="max-w-xl">
        <AlertTitle>
          Heads up
        </AlertTitle>

        <AlertDescription>
          This is a neutral message. Use it for non-critical information.
        </AlertDescription>
      </Alert>
    </Preview>
  </Tab>

  <Tab value="Code">
    ```tsx title="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>
      );
    }
    ```
  </Tab>
</Tabs>

<Callout type="info" title="Typography note">
  Prefer plain text inside `AlertDescription`. Avoid nesting extra paragraph tags when the component already renders text semantics.
</Callout>

## When to use Alert

Use Alert when the message should remain visible in context.

<DocsFeatureGrid
  columns={3}
  tone="platform"
  items={[
  {
    title: 'Page notice',
    description:
      'Explain something important before the user continues.',
    icon: Info,
  },
  {
    title: 'Success result',
    description:
      'Confirm that an important action completed successfully.',
    icon: CheckCircle,
    tone: 'success',
  },
  {
    title: 'Blocking error',
    description:
      'Explain what failed and what the user can do next.',
    icon: ShieldAlert,
    tone: 'danger',
  },
]}
/>

### Variants

Variants reflect the semantic meaning of the message.

<Tabs items={["Preview", "Code"]}>
  <Tab value="Preview">
    <Preview>
      <div className="grid max-w-xl 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>
    </Preview>
  </Tab>

  <Tab value="Code">
    ```tsx title="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>
      );
    }
    ```
  </Tab>
</Tabs>

### Available variants

| 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                           |

<Callout type="info" title="Token behavior">
  `default` and `info` intentionally share the same visual language in the current v1 token set.
</Callout>

### Announcements with ariaLive

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 |

The resulting `role` and `aria-live` are deterministic: they are always derived from `ariaLive` and take precedence over any native `role` or `aria-live` value passed through the rest of the component's props.

<Tabs items={["Preview", "Code"]}>
  <Tab value="Preview">
    <Preview>
      <div className="grid max-w-xl 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 live announcement for this message.
          </AlertDescription>
        </Alert>
      </div>
    </Preview>
  </Tab>

  <Tab value="Code">
    ```tsx title="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>
      );
    }
    ```
  </Tab>
</Tabs>

<Callout title="Accessibility rule">
  Use `assertive` only for urgent errors. Overusing assertive announcements creates a noisy experience for screen reader users.
</Callout>

### With indicator

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

<Tabs items={["Preview", "Code"]}>
  <Tab value="Preview">
    <Preview>
      <Alert variant="warning" className="max-w-xl">
        <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>
    </Preview>
  </Tab>

  <Tab value="Code">
    ```tsx title="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>
      );
    }
    ```
  </Tab>
</Tabs>

<Callout type="info" title="Icon rule">
  If the icon is decorative, add `aria-hidden="true"`. The text must carry the meaning.
</Callout>

### Usage patterns

<Steps>
  <Step>
    #### Use inline alerts for persistent states

    Use Alert when the message should remain visible near the relevant content.
  </Step>

  <Step>
    #### Use the variant that matches meaning

    Choose `success`, `warning`, or `destructive` only when the message carries that semantic intent.
  </Step>

  <Step>
    #### Keep copy specific and actionable

    Explain what happened and what the user can do next.
  </Step>

  <Step>
    #### Announce only what matters

    Use `polite` for status updates and `assertive` only for critical failures.
  </Step>
</Steps>

## Alert vs Toast

| 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 |

<Callout title="Decision rule">
  If the user needs the message to complete the task, use Alert. If the message is temporary confirmation, use Toast.
</Callout>

## API

| 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:

```ts title="alert-types.ts"
React.HTMLAttributes<HTMLDivElement>
```

### TypeScript types

```ts title="alert-types.ts"
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"`.
* `ariaLive="assertive"` renders `role="alert"`.
* `ariaLive="off"` removes live-region announcements.
* The computed `role` and `aria-live` cannot be silently overridden by other props; `ariaLive` is the single source of truth.
* Do not rely on color alone to communicate meaning.
* Decorative indicators should use `aria-hidden="true"`.
* Keep alert copy clear, short, and actionable.

## Prefer / avoid

<PreferAvoid
  prefer={[
  'short and actionable copy',
  'inline placement near the issue',
  'semantic variants for real states',
  'polite announcements by default',
  'assertive only for critical errors',
]}
  avoid={[
  'using alerts for temporary notifications',
  'vague copy like “Something went wrong” alone',
  'color-only meaning',
  'assertive announcements for every message',
  'placing blocking alerts far from the task',
]}
/>

## Common questions

<Accordions type="single">
  <Accordion title="Should success messages use Alert or Toast?">
    Use Alert when the confirmation must remain visible in context. Use Toast for short-lived confirmations after non-blocking actions.
  </Accordion>

  <Accordion title="Should every destructive alert use assertive?">
    No. Use `assertive` only when the message is urgent and the user must know immediately.
  </Accordion>

  <Accordion title="Can an Alert contain actions?">
    Yes, but keep actions secondary and focused. If the flow becomes complex, use a dedicated form, Dialog, or page section.
  </Accordion>

  <Accordion title="Should icons communicate meaning alone?">
    No. Icons should reinforce meaning. The text must explain the message.
  </Accordion>
</Accordions>

## Related

<DocsLinks
  variant="list"
  tone="platform"
  items={[
  {
    title: 'Colors',
    href: '/docs/design-system/colors',
    description:
      'Semantic tokens for borders, surfaces, and state colors.',
    icon: Palette,
  },
  {
    title: 'Empty, loading, and error states',
    href: '/docs/guides/empty-loading-error',
    description:
      'Learn when to use Alert for async product failures.',
    icon: CircleAlert,
  },
  {
    title: 'Toast',
    href: '/docs/ui/toast',
    description:
      'Temporary feedback for non-blocking actions.',
    icon: BellRing,
  },
  {
    title: 'Accessibility',
    href: '/docs/ui/accessibility',
    description:
      'Build accessible product feedback with clear semantics and announcements.',
    icon: Accessibility,
  },
]}
/>