iconiq
—Open GitHub

Alert

Polished inline notices and toast updates for concise feedback.

Preview a

alert below.

Installation

npx shadcn@latest add @iconiq/alert

Props

Alert

13 props

Root container for a single notice. Uses a compact grid layout with optional leading icon, compound title and description slots, legacy prop support, and inline or toast behavior.
childrenReactNode
Preferred compound API. Pass an optional leading icon followed by AlertTitle and AlertDescription.
iconReactNode
Legacy leading visual prop. Compound children can also provide the leading icon as the first child.
titleReactNode
Legacy title prop rendered with the same AlertTitle styling. Prefer AlertTitle for new code.
messageReactNode
Legacy description prop rendered with the same AlertDescription styling. Prefer AlertDescription for new code.
actionReactNode
Optional action row rendered beneath the message, useful for a single follow-up button or link such as Undo or View details.
appearance"default" | "destructive" | "warning"
Default"default"
Visual tone for the alert surface. Destructive shifts toward error colors; warning uses a warm amber surface with muted description text.
size"sm" | "md" | "lg" | "xl"
Default"md"
Preset max width for inline and toast alerts. sm is 320px, md is 400px, lg is 480px, and xl is 560px.
widthstring | number
Custom max width. Pass a CSS length such as 28rem or a pixel number. Overrides size when set.
dismissibleboolean
Defaultlegacy: true; compound inline: false
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.
variant"inline" | "toast"
Default"inline"
Explicitly chooses layout behavior. Toasts portal to document.body and use fixed viewport positioning, while inline alerts stay in normal document flow.
position"top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right"
Optional toast placement. Providing a position also upgrades the component to toast behavior, and omitted toast positions default to top-right.
timeoutnumber
Defaultlegacy/toast: 5000; compound inline: 0
Auto-dismiss delay in milliseconds. Passing 0 disables the timer; compound inline alerts default to no timer so static notices stay visible.
onDismiss() => void
Called after the component finishes its exit transition, regardless of whether dismissal came from the close button or the timeout effect.

Notes

Use size for preset widths or pass width for a custom max width. md defaults to 400px.
Every positioned alert snaps to a full-width top placement on small screens, then switches to the requested corner at the sm breakpoint.
Inline alerts use role="alert"; toast alerts use role="status" with aria-live="polite" and keep title and message linked with aria-labelledby and aria-describedby.
The alert keeps its own visible state internally when dismissal is enabled, so toast usage is designed for fire-and-forget notifications rather than parent-controlled open state.
Hovering or focusing the alert pauses auto-dismiss, which gives people more time to read and makes the close target less stressful to hit.

AlertTitle

2 props

Primary line for the compound alert API. Renders in the second grid column beside the optional icon.
childrenReactNode
Required
Short title or inline formatted heading content.
classNamestring
Merged with the title typography classes for one-off styling.

AlertDescription

2 props

Secondary line for the compound alert API. Renders beneath the title in the second grid column and links to the root with aria-describedby.
childrenReactNode
Required
Supporting message content. Keep it concise for compact inline notices and toast updates.
classNamestring
Merged with the description typography classes for one-off styling.