Alert

Polished inline notices and toast updates for concise feedback.

Installation

npx shadcn@latest add @iconiq/alert

File Structure

Usage

"use client";

import {
  Alert,
  AlertAction,
  AlertDescription,
  AlertTitle,
} from "@/components/ui/alert";
import { TriangleAlert } from "lucide-react";

export function AlertDemo() {
  return (
    <Alert appearance="warning">
      <TriangleAlert />
      <AlertTitle>Unsaved changes detected</AlertTitle>
      <AlertDescription>
        Save now or recent edits may be lost.
      </AlertDescription>
    </Alert>
  );
}

Props

Props
Description

Alert

children

Preferred compound API. Pass an optional leading icon followed by AlertTitle and AlertDescription.

Type ReactNode

icon

Legacy leading visual prop. Compound children can also provide the leading icon as the first child.

Type ReactNode

title

Legacy title prop rendered with the same AlertTitle styling. Prefer AlertTitle for new code.

Type ReactNode

message

Legacy description prop rendered with the same AlertDescription styling. Prefer AlertDescription for new code.

Type ReactNode

action

Optional action row rendered beneath the message, useful for a single follow-up button or link such as Undo or View details.

Type ReactNode

appearance

Visual tone for the alert surface. Success and info use semantic green and blue surfaces; destructive shifts toward error colors; warning uses a warm amber surface with muted description text.

Type "default" | "success" | "info" | "destructive" | "warning"·Default "default"

size

Preset max width for inline and toast alerts. sm is 320px, md is 400px, lg is 480px, and xl is 560px.

Type "sm" | "md" | "lg" | "xl"·Default "md"

width

Custom max width. Pass a CSS length such as 28rem or a pixel number. Overrides size when set.

Type string | number

dismissible

Controls whether the close button is rendered. Compound inline alerts are static by default; toast and legacy prop alerts remain dismissible unless you opt out.

Type boolean·Default legacy: true; compound inline: false

variant

Explicitly chooses layout behavior. Toasts portal to document.body and use fixed viewport positioning, while inline alerts stay in normal document flow.

Type "inline" | "toast"·Default "inline"

position

Optional toast placement. Providing a position also upgrades the component to toast behavior, and omitted toast positions default to top-right.

Type "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right"

timeout

Auto-dismiss delay in milliseconds. Passing 0 disables the timer; compound inline alerts default to no timer so static notices stay visible.

Type number·Default legacy/toast: 5000; compound inline: 0

open

Controlled visibility. Pair with onOpenChange when parent state should own whether the alert is shown.

Type boolean

defaultOpen

Initial visibility for uncontrolled usage. Ignored when open is provided.

Type boolean·Default true

onOpenChange

Called when visibility changes from dismissal, timeout, Escape, or the close button.

Type (open: boolean) => void

titleLines

Maximum title lines before truncation. Pass none to allow the title to wrap freely.

Type 1 | 2 | 3 | "none"·Default 1

onDismiss

Called after the component finishes its exit transition, regardless of whether dismissal came from the close button or the timeout effect.

Type () => void

AlertTitle

children

Short title or inline formatted heading content.

Type ReactNode

className

Merged with the title typography classes for one-off styling.

Type string

AlertDescription

children

Supporting message content. Keep it concise for compact inline notices and toast updates.

Type ReactNode

className

Merged with the description typography classes for one-off styling.

Type string

AlertAction

children

Follow-up controls such as a single button or text link. Keep actions concise.

Type ReactNode

className

Merged with the action row layout classes.

Type string

Motion and lifecycle

Alert uses AnimatePresence for mount and exit, with separate variants for the container, icon, and text stack.

Entry uses long fluid easing on opacity, vertical drift, scale, and blur so the alert settles in rather than snapping.

Exit keeps the same direction with a softer, slightly slower fade so dismissal still feels continuous.

Child text and the icon only fade on exit, which keeps the container motion cohesive.

prefers-reduced-motion swaps blur, scale, and drift for short opacity fades on the container, text, and icon.

The timeout effect is cleared on cleanup, so unmounting or rerendering the alert does not leak timers.

When position is set, the component waits until after mount before calling createPortal to avoid touching document during server render.

Dismissal callbacks wait until the exit transition completes, so parent cleanup does not cut off the visual exit early.

Registry bundle

Install the exact registry entry shown on the right when you want the component file and its declared runtime dependencies together.

Dependencies: motion, class-variance-authority.

Install into components/ui/alert.tsx (or your preferred UI folder) so imports match the usage examples.

The provider switch is shown for section consistency, but both Radix UI and Base UI options are disabled because Alert does not ship primitive-specific variants here.

The generated registry file is /r/alert.json.

Contact

Additionally, if you find any bug or issue, feel free to raise an issue.