---
title: Alert
description: Displays a callout for user attention.
icon: triangle-alert
author:
  name: shadcn
  url: https://github.com/shadcn
mode: wide
---

<PoweredBy packages={[{ name: 'Shadcn UI', url: 'https://ui.shadcn.com/docs/components/alert' }]} />

### Installation

```package-install
npx shadcn@latest add @redpanda/alert
```

<ComponentPreview name="alert-demo" />

## Usage

Place dismiss or other independent controls inside `AlertAction`. It owns a separate
leading-row grid track spanning the title and description, so text cannot run under
the action. It is no longer absolutely positioned. Do not add right-padding or
absolute-position overrides to `Alert` or its action controls.

### Basic Example

```tsx lineNumbers
import { Alert, AlertAction, AlertDescription, AlertTitle } from '@/components/redpanda-ui/alert';
import { Info } from 'lucide-react';

<Alert variant="informative">
  <Info />
  <AlertTitle>Heads up!</AlertTitle>
  <AlertDescription>You can add components and dependencies to your app using the cli.</AlertDescription>
</Alert>;
```

### Info Alert

```tsx lineNumbers
import { Info } from 'lucide-react';

<Alert variant="informative">
  <Info />
  <AlertTitle>Information</AlertTitle>
  <AlertDescription>
    This is a general information alert. Use it to provide helpful context or neutral updates.
  </AlertDescription>
</Alert>;
```

### Success Alert

```tsx lineNumbers
import { CheckCircle2 } from 'lucide-react';

<Alert variant="success">
  <CheckCircle2 />
  <AlertTitle>Success</AlertTitle>
  <AlertDescription>Your changes have been saved successfully.</AlertDescription>
</Alert>;
```

### Warning Alert

```tsx lineNumbers
import { AlertTriangle } from 'lucide-react';

<Alert variant="warning">
  <AlertTriangle />
  <AlertTitle>Warning</AlertTitle>
  <AlertDescription>
    Your trial period expires in 3 days. Upgrade your plan to continue using all features.
  </AlertDescription>
</Alert>;
```

### Destructive Alert

```tsx lineNumbers
import { AlertCircle } from 'lucide-react';

<Alert variant="destructive">
  <AlertCircle />
  <AlertTitle>Error occurred</AlertTitle>
  <AlertDescription>Your session has expired. Please sign in again to continue.</AlertDescription>
</Alert>;
```

### Neutral Alert

A toneless notice for banners that inform without carrying a status.

```tsx lineNumbers
import { Bell } from 'lucide-react';

<Alert variant="neutral">
  <Bell />
  <AlertTitle>Maintenance window</AlertTitle>
  <AlertDescription>Scheduled maintenance runs Sunday 02:00–04:00 UTC. No action is needed.</AlertDescription>
</Alert>;
```

### Without Icon

```tsx lineNumbers
<Alert>
  <AlertTitle>No Icon Alert</AlertTitle>
  <AlertDescription>
    This alert doesn't include an icon. The layout automatically adjusts when no icon is present.
  </AlertDescription>
</Alert>
```

### Simple Description Only

```tsx lineNumbers
import { CheckCircle } from 'lucide-react';

<Alert>
  <CheckCircle />
  <AlertDescription>Your changes have been saved successfully.</AlertDescription>
</Alert>;
```

## When to use

Use alerts to communicate important messages that require user attention. Alerts and warnings are often placed directly on the page to provide immediate feedback and build trust with users.

### Placement Guidelines

**Generic errors:** Place at the top of the page when the error affects the entire page or system.

**Field-specific errors:** Place as close to the relevant field or component as possible for immediate context.

### Alert vs Toast vs Modal

Choose the right notification pattern based on the message characteristics:

```mermaid
graph TD;
    A[User needs to be notified<br/>e.g. error, alert, confirmation, etc] --> B{Is the notification transient?<br/>e.g. after an action, can be<br/>solved by reloading};

    B -->|Yes| C{Does the notification need<br/>added emphasis, a lot of<br/>content or multiple actions};
    B -->|No| D{Is the notification part of<br/>a multi step modal flow?};

    C -->|No| E[Toast];
    C -->|Yes| F[Modal];

    D -->|Yes| F;
    D -->|No| G{Is the notification blocking<br/>and part of a multi step full<br/>page flow? e.g. Create<br/>cluster flow};

    G -->|Yes| H[Full page error];
    G -->|No| I{Is the notification a blocking<br/>error on displaying a page?<br/>e.g. 404};

    I -->|Yes| H;
    I -->|No| J[Alert banner];

    classDef recommended fill:#4ade80,stroke:#22c55e,stroke-width:2px,color:#000;
    classDef decision fill:#e0e7ff,stroke:#818cf8,stroke-width:2px,color:#000;

    class E,F,H,J recommended;
    class A,B,C,D,G,I decision;
```

**Use Alert when:**

- Displaying longer-lived feedback or information (e.g., recommendations, resource errors)
- The notification is not blocking and should persist on the page
- Showing system-wide messages or status updates in resource overviews, modals, or forms
- Communicating important context about the current page or action
- The error/information is blocking page display (e.g., 404 errors)

**Use Toast when:**

- The notification is transient and appears after an action
- The message can be resolved by reloading or is temporary
- You don't need added emphasis, extensive content, or multiple actions
- Providing brief confirmations or status updates

**Use Modal when:**

- The notification is transient but requires added emphasis
- You need to display a lot of content or multiple actions
- The notification is part of a multi-step modal flow
- User confirmation or input is required before proceeding

### Best Practices

**Communication and Feedback:**

- Use notifications sparingly as they are disruptive
- Provide immediate feedback to build trust with users
- Choose the appropriate variant based on message severity:
  - `informative` - General information and neutral updates
  - `success` - Successful operations and confirmations
  - `warning` - Important warnings that need attention
  - `destructive` - Errors and critical issues
  - `neutral` - Notices with no status to carry, such as a maintenance window

**Alert Banners:**

- Use for longer-lived feedback in resource overviews, modals, and forms
- Ideal for recommendations, error states, or important information
- Keep messages clear and actionable

**Don't use Alert when:**

- The message is purely decorative (use regular text instead)
- You need immediate user confirmation for critical actions (use Modal/Dialog)
- The message is field-specific (use inline field-level validation)

## Anatomy

The Alert component has a simple, flexible structure:

```
Alert Container (role="alert")
┌─────────────────────────────────────────────────┐
│ [Icon]  AlertTitle (optional)                   │
│         AlertDescription (optional)             │
└─────────────────────────────────────────────────┘

Layout Grid Structure:
┌─────────────┬───────────────────────────────────┐
│             │                                   │
│   [Icon]    │  AlertTitle                       │
│   (16px)    │  AlertDescription                 │
│             │                                   │
└─────────────┴───────────────────────────────────┘
 Grid Column 1   Grid Column 2
```

**Component Hierarchy:**

1. **Alert** (Container): Main wrapper with variant styling and grid layout
2. **Icon** (Optional): Visual indicator placed in the first grid column
3. **AlertTitle** (Optional): Bold heading text in the second grid column
4. **AlertDescription** (Optional): Descriptive text below the title

**CSS Grid Layout:**

- **With Icon**: `grid-cols-[calc(var(--spacing)*4)_1fr]` - Fixed icon column + flexible content
- **Without Icon**: `grid-cols-[0_1fr]` - No icon space + full-width content
- **Gap**: 12px horizontal gap between icon and text content

**Variants:** Each variant pairs a tone-tinted surface (Badge "subtle" palette) with a matching outline border and colored icon, using dark-safe semantic tokens. Title and description use high-contrast `text-foreground` in both themes; the tone is carried by the surface, border, and icon.

- **info**: Blue color scheme for general information and neutral updates
- **success**: Green color scheme for successful operations and confirmations
- **warning**: Amber color scheme for important warnings and cautionary messages
- **destructive**: Red color scheme for errors and critical issues
- **neutral**: The secondary wash and default border, with a subtle icon, for notices without a status

## Examples

### Default

<ComponentPreview
  name="alert-demo"
  title="An alert with an icon, title and description."
  description="An alert with an icon, title and description. The title says 'Heads up!' and the description is 'You can add components to your app using the cli.'."
/>

### Severity Variants

<ComponentPreview
  name="alert-variants-demo"
  description="Alert severity variants side-by-side: info, success, warning, and error."
/>

### With Actions

<ComponentPreview
  name="alert-with-action-demo"
  description="Alert with title, description, and inline primary/dismiss action buttons."
/>

### Dismissible

<ComponentPreview
  name="alert-dismissible-demo"
  description="User-dismissible alert with an accessible close affordance."
/>

## Credits

- We take our inspiration from [Shadcn UI](https://ui.shadcn.com/docs/components/alert) for the alert component and style.