Alert

Purpose and Scope

The Alert component is the ARIA-family callout used when an interface needs to draw attention to contextual information without interrupting the user. In the documentation source, it is described as a component that “Displays a callout for user attention,” which places it between plain text feedback and modal flows. Use it for heads-up notices, validation-adjacent explanations, upgrade prompts, and non-blocking warnings where the user can keep working. If the message requires an explicit confirmation before continuing, the neighboring Alert Dialog pattern is the stronger fit because it is documented as a modal dialog that interrupts the user and expects a response.

Sources: apps/v4/content/docs/components/aria/alert.mdx, apps/v4/content/docs/components/aria/alert-dialog.mdx

Alert follows the shadcn/ui composition model: install source code into your app, import the exported pieces from your local @/components/ui/alert path, then customize the classes and structure directly. The official examples show an icon, title, description, and optional action arranged inside a single Alert container. That arrangement is intentionally small and readable, but it still supports product-level customization through variants and classes. In practice, Alert should be treated as a reusable layout primitive rather than a closed widget; teams can adjust color, spacing, typography, and action content to match their design system.

Sources: apps/v4/content/docs/components/aria/alert.mdx, apps/v4/content/docs/changelog/2025-12-shadcn-create.mdx

Relevant Source Files

• apps/v4/content/docs/components/aria/alert.mdx - Defines the Alert page metadata, installation flow, import example, composition tree, documented variants, RTL preview, and API reference for Alert, AlertTitle, AlertDescription, and AlertAction.
• apps/v4/content/docs/components/aria/alert-dialog.mdx - Provides the adjacent interruptive-dialog pattern, useful for explaining when a non-modal alert is not enough and a response-oriented alert dialog is more appropriate.
• apps/v4/content/docs/changelog/2024-08-npx-shadcn-init.mdx - Explains the rewritten CLI model behind npx shadcn add, including component installation, dependency handling, framework support, aliases, and registry distribution.
• apps/v4/content/docs/changelog/2025-04-shadcn-2-5.mdx - Documents “resolve anywhere,” which matters when registry-installed components and their imports are placed outside a fixed file structure.
• apps/v4/content/docs/changelog/2025-12-shadcn-create.mdx - Explains the customization direction behind newer visual styles and component-library choices, which frames Alert as code that can be transformed to match a project preset.
• apps/v4/content/docs/changelog/2026-04-shadcn-apply.mdx - Describes applying presets to existing projects while keeping base and RTL settings, which is relevant when Alert styling changes after initial installation.

Installation and Project Fit

Install Alert with the CLI when your project already has shadcn/ui configured. The documented command is short because the CLI resolves the registry item and writes the component into your local project. Manual installation remains available for teams that want to copy the component source themselves; the docs instruct users to copy the components/ui/alert.tsx source and then update import paths to match the project setup. That import-path step is important in monorepos or apps that use a prefix other than @, because shadcn/ui components are local code and should follow the aliases defined by the app.

Sources: apps/v4/content/docs/components/aria/alert.mdx, apps/v4/content/docs/changelog/2024-08-npx-shadcn-init.mdx

npx shadcn@latest add alert

The CLI context matters because Alert is distributed as code, not only as a package import. The August 2024 CLI changelog says components can be installed with npx shadcn add, and it ties that workflow to a broader registry model where components can bring their own dependencies, update project files, and respect aliases. Alert itself is a simple component, but it benefits from the same installation system as more complex registry items. When a project later changes its visual direction, the create and apply changelogs describe a newer preset-based workflow where component code, theme values, fonts, icons, and RTL settings can be adapted without treating installed UI as untouchable vendor code.

Sources: apps/v4/content/docs/changelog/2024-08-npx-shadcn-init.mdx, apps/v4/content/docs/changelog/2025-12-shadcn-create.mdx, apps/v4/content/docs/changelog/2026-04-shadcn-apply.mdx

Composition and Usage

The standard Alert import exposes four documented pieces: Alert, AlertTitle, AlertDescription, and AlertAction. The container owns the callout surface and variant. The title communicates the short message, the description carries supporting content, and the action slot places a button or other control in the alert. The docs also show an icon as a direct child of the container even though it is not listed as a named export. That is the typical shadcn/ui pattern: icons can come from your chosen icon package and participate in layout through the component’s child structure and CSS.

Sources: apps/v4/content/docs/components/aria/alert.mdx

import {
  Alert,
  AlertAction,
  AlertDescription,
  AlertTitle,
} from "@/components/ui/alert"

<Alert>
  <InfoIcon />
  <AlertTitle>Heads up!</AlertTitle>
  <AlertDescription>
    You can add components and dependencies to your app using the cli.
  </AlertDescription>
  <AlertAction>
    <Button variant="outline">Enable</Button>
  </AlertAction>
</Alert>

Read the composition tree as a layout contract rather than a required semantic hierarchy. The documented shape is Alert containing an icon, AlertTitle, AlertDescription, and AlertAction. Keep the title concise, because it is the part users scan first. Use the description for explanatory text, links, or a sentence that tells the user what changed and what they can do next. Add AlertAction only when the callout has an immediate, low-risk response such as enabling a setting, opening details, or retrying a background operation. If the action is destructive or must block continuation, use Alert Dialog instead.

Sources: apps/v4/content/docs/components/aria/alert.mdx, apps/v4/content/docs/components/aria/alert-dialog.mdx

Variants, Custom Colors, and RTL

Alert has a documented variant prop with two values: default and destructive. The default variant is appropriate for neutral or informational callouts. The destructive variant is for states that need stronger warning treatment, such as irreversible consequences, dangerous settings, or errors that could lead to data loss. The docs phrase this as using variant="destructive" to create a destructive alert. That wording is intentionally visual and behavioral: the variant changes the component’s presentation, while the surrounding copy and action design determine whether the user understands the risk.

Sources: apps/v4/content/docs/components/aria/alert.mdx

Custom colors are applied by adding classes to the Alert component. The docs give bg-amber-50 dark:bg-amber-950 as an example, which shows that color customization is expected to live at the callout surface and can include dark-mode-specific tokens. This is consistent with shadcn/ui’s larger direction: the changelog for npx shadcn create emphasizes solid defaults that are meant to be changed, including colors, spacing, structure, fonts, and component-library choices. For Alert, prefer semantic color decisions that match the message type, and make sure any custom foreground, border, icon, and action colors remain legible in both light and dark contexts.

Sources: apps/v4/content/docs/components/aria/alert.mdx, apps/v4/content/docs/changelog/2025-12-shadcn-create.mdx

RTL support is documented through a dedicated RTL preview with direction="rtl" and a pointer to the RTL configuration guide. The Alert source page does not present RTL as a separate component; it presents it as the same component rendered under a right-to-left direction. That matters for AlertAction, because its API description says the action element is positioned absolutely in the top-right corner of the alert. When testing RTL layouts, verify that the icon, text block, and action affordance still read naturally for the locale and that any custom classes do not hard-code left-to-right spacing assumptions.

Sources: apps/v4/content/docs/components/aria/alert.mdx, apps/v4/content/docs/changelog/2026-04-shadcn-apply.mdx

API Reference

The Alert API is intentionally compact. The public surface documented by the MDX page is a set of composable React components plus a small variant prop on the root. The root Alert displays the callout. AlertTitle displays the title, AlertDescription displays the description or body content, and AlertAction displays an action element such as a button. Each subcomponent accepts className, which is the customization escape hatch for per-instance styling. The documented action slot is positioned absolutely in the top-right corner, so test long titles, responsive widths, and RTL direction whenever you place interactive content there.

Sources: apps/v4/content/docs/components/aria/alert.mdx

Use this reference to keep component instances predictable. Start with Alert and one readable content path: title plus description. Add an icon when it improves recognition, not when it merely decorates the message. Add AlertAction when the user can take a direct action from the callout. Choose destructive only when the situation is genuinely risky or irreversible; otherwise, use the default variant with custom classes for lower-severity statuses such as warning, success, or informational notices. Because the source page treats custom colors as classes, avoid inventing extra variant names unless your local component code has been intentionally extended.

Sources: apps/v4/content/docs/components/aria/alert.mdx

Alert vs. Alert Dialog

Alert and Alert Dialog solve related but different interface problems. Alert is a callout: it sits in the page and asks for attention while preserving the user’s current flow. Alert Dialog is modal: it interrupts the user with important content and expects a response. The Alert Dialog docs include trigger, header, media, title, description, footer, cancel, and action pieces, plus a size prop for the dialog content. Those extra parts are signs that the pattern is meant for decisions, confirmations, and interruption, not for lightweight status communication.

Sources: apps/v4/content/docs/components/aria/alert-dialog.mdx, apps/v4/content/docs/components/aria/alert.mdx

A useful decision rule is to ask whether the user must answer before proceeding. If not, use Alert and keep it concise. If yes, use Alert Dialog and provide cancel and continue paths. For destructive flows, do not rely on a red Alert with a button if the consequence needs confirmation; the dialog pattern makes the response explicit. Conversely, do not use a modal dialog for routine background information, because it adds friction and can make the product feel noisy. The two components are designed to sit near each other in the catalog while preserving this difference in interaction weight.

Sources: apps/v4/content/docs/components/aria/alert-dialog.mdx

Next Steps

After installing Alert, add one production instance and test it in the same states your users will see: default, destructive, with an action, with long description text, in dark mode, and in RTL if your project supports right-to-left languages. If your team uses presets, remember that shadcn apply can update theme, colors, CSS variables, fonts, and icons while keeping current base and RTL settings, so re-check Alert after preset changes. For deeper context, read the ARIA components overview, the Alert Dialog page, theming guidance, dark-mode guidance, and the CLI page that explains registry-based installation workflows.

Sources: apps/v4/content/docs/changelog/2026-04-shadcn-apply.mdx, apps/v4/content/docs/changelog/2025-04-shadcn-2-5.mdx, apps/v4/content/docs/changelog/2024-08-npx-shadcn-init.mdx