Alert

Polished inline notices and toast updates for concise feedback.

Installation

npx shadcn@latest add @iconiq/alert

Props

Alert

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

Default legacy: 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.

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

timeoutnumber

Default legacy/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.

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

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

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.

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.

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.

This page lives in the Components section, but the install itself is the shared Iconiq alert primitive rather than a Radix UI or Base UI wrapper.

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.