# Alert

## Overview

An inline message banner used to communicate status, feedback, or important contextual information directly within the page content — without interrupting the user flow. Unlike `Sonner` (toast notifications), alerts are persistent and visible at all times.

**Optimization**: The Xertica UI `Alert` component automatically renders a semantic icon based on the chosen `variant`. You do not need to add icons manually unless you want to override the default.

---

## When to Use

- Inline warnings about data state ("This record is read-only")
- Information banners about required actions ("Please verify your email")
- Success confirmation areas within a form or page section
- Error messages from API responses or forms

---

## Variants

| Variant       | Color        | Default Icon  | Usage                         |
| ------------- | ------------ | ------------- | ----------------------------- |
| `default`     | Neutral      | Info          | General information           |
| `info`        | Blue accent  | Info          | Informational context         |
| `success`     | Green accent | CheckCircle   | Confirmation or success state |
| `warning`     | Amber accent | AlertTriangle | Cautionary information        |
| `destructive` | Red          | XCircle       | Errors, critical warnings     |

---

## Anatomy

```tsx
<Alert variant="info">
  <AlertTitle>Title</AlertTitle>
  <AlertDescription>Detailed message here.</AlertDescription>
</Alert>
```

---

## Props

### Alert

| Prop        | Type                                                             | Default     | Description                                                               |
| ----------- | ---------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------- |
| `variant`   | `'default' \| 'info' \| 'success' \| 'warning' \| 'destructive'` | `'default'` | Visual style and automatic icon                                           |
| `icon`      | `ReactNode`                                                      | —           | Overrides the default semantic icon. Set to `null` to hide the icon area. |
| `className` | `string`                                                         | —           | Additional CSS classes                                                    |

---

## Examples

### Informational (Automatic Icon)

```tsx
import { Alert, AlertDescription, AlertTitle } from 'xertica-ui/ui';

<Alert variant="info">
  <AlertTitle>Note</AlertTitle>
  <AlertDescription>
    This data is refreshed every 24 hours. Last updated: today at 08:00.
  </AlertDescription>
</Alert>;
```

### Warning

```tsx
<Alert variant="warning">
  <AlertTitle>Attention Required</AlertTitle>
  <AlertDescription>
    Your subscription expires in 3 days. Renew to avoid service interruption.
  </AlertDescription>
</Alert>
```

### Custom Icon

```tsx
import { Terminal } from 'lucide-react';

<Alert icon={<Terminal className="size-4" />}>
  <AlertTitle>System Prompt</AlertTitle>
  <AlertDescription>Executing automated deployment script...</AlertDescription>
</Alert>;
```

---

## AI Rules

- **Do not manually add icons inside `<Alert>`** — let the component handle them via `variant` or `icon` prop.
- Always include an `AlertTitle` for clear information hierarchy.
- Use `destructive` for errors and critical failure states.
- Place alerts close to the relevant content (e.g., top of a form or below a header).

---

## Related Components

- [`Sonner`](./sonner.md) — For transient toast notifications
- [`AlertDialog`](./alert-dialog.md) — For destructive confirmation modals