Alert

[!NOTE] The default variant uses text-primary for the icon (Helix navy blue). The destructive variant uses text-destructive for consistency. The warning variant uses the orange palette (tc-orange-50/200/900), matching the outlineOrange badge. The info variant uses the navy palette (tc-navy-50/200 + text-primary), matching the outlineNavy badge. The success variant uses the sage palette (tc-sage-50/200/600), matching the outlineSage badge. The error variant uses the berry palette (tc-berry-50/200/600), matching the outlineBerry badge.

Import

import { Alert, AlertTitle, AlertDescription, AlertAction } from "@timelycare/helix-ui"

Props

interface AlertProps {
  variant?: "default" | "destructive" | "warning" | "info" | "success" | "error"
  className?: string
  children: React.ReactNode
}

interface AlertTitleProps {
  className?: string
  children: React.ReactNode
}

interface AlertDescriptionProps {
  className?: string
  children: React.ReactNode
}

interface AlertActionProps {
  className?: string
  children: React.ReactNode
}

Variants

Choosing a Variant

• Default: General system status, neutral notices
• Destructive: Critical errors or destructive actions requiring immediate attention
• Warning: Cautionary notices where the user should take care (uses orange palette, matching outlineOrange badge)
• Info: Informational notices, tips, and updates (uses navy palette, matching outlineNavy badge)
• Success: Positive confirmations, completed actions (uses sage palette, matching outlineSage badge)
• Error: Non-critical errors and failure states with a softer tone than destructive (uses berry palette, matching outlineBerry badge)

Styling

Typography

Container

Icon Grid Placement

Title

• font-medium (600)
• col-start-2 when icon is present (via group-has-[>svg]/alert:col-start-2)
• Color inherits from container (text-card-foreground or text-destructive)

Description

• text-muted-foreground text-sm
• text-balance md:text-pretty for nicer wrapping
• Destructive variant: text-destructive/90 (applied via parent slot selector)

AlertAction

• absolute top-2 right-2
• Container adds pr-18 when AlertAction is present
• Action buttons should use size xs (h-7 px-3 text-xs font-medium)

Icons

Size: size-4 (16×16px, default when no explicit size class) Alignment: Grid-based — row-span-2 translate-y-0.5 text-current

Icons are placed as direct children of the Alert container. The grid auto-handles positioning — no wrapper div needed.

import { CircleCheck } from "lucide-react"

<Alert>
  <CircleCheck className="size-4" />
  <AlertTitle>Title</AlertTitle>
</Alert>

States

Alert is a static display component. Any action buttons within it have their own states.

Common Patterns

Success Alert (colored)

import { CircleCheck } from "lucide-react"

<Alert variant="success">
  <CircleCheck className="size-4" />
  <AlertTitle>Changes saved</AlertTitle>
  <AlertDescription>
    Your changes have been saved successfully.
  </AlertDescription>
</Alert>

Error Alert (colored)

import { AlertCircle } from "lucide-react"

<Alert variant="error">
  <AlertCircle className="size-4" />
  <AlertTitle>Something went wrong</AlertTitle>
  <AlertDescription>
    We couldn't process your request. Please try again.
  </AlertDescription>
</Alert>

Destructive Alert

import { AlertCircle } from "lucide-react"

<Alert variant="destructive">
  <AlertCircle className="size-4" />
  <AlertTitle>Something went wrong!</AlertTitle>
  <AlertDescription>
    Your session has expired. Please log in again.
  </AlertDescription>
</Alert>

With Action Button

<Alert>
  <CircleCheck className="size-4" />
  <AlertTitle>Dark mode is now available</AlertTitle>
  <AlertDescription>Enable it under your profile settings to get started.</AlertDescription>
  <AlertAction>
    <Button size="xs">Enable</Button>
  </AlertAction>
</Alert>

Error with Retry Action

<Alert variant="destructive">
  <AlertCircle className="size-4" />
  <AlertTitle>Failed to load data</AlertTitle>
  <AlertDescription className="flex items-center justify-between">
    <span>There was a problem fetching your data.</span>
    <Button variant="outline" size="sm" onClick={retry}>
      <RotateCcw className="size-4 mr-2" />
      Retry
    </Button>
  </AlertDescription>
</Alert>

Warning Alert

import { TriangleAlert } from "lucide-react"

<Alert variant="warning">
  <TriangleAlert className="size-4" />
  <AlertTitle>Storage almost full</AlertTitle>
  <AlertDescription>
    You have used 90% of your available storage. Consider upgrading your plan.
  </AlertDescription>
</Alert>

Info Alert

import { Info } from "lucide-react"

<Alert variant="info">
  <Info className="size-4" />
  <AlertTitle>New version available</AlertTitle>
  <AlertDescription>
    Version 2.4.0 includes performance improvements and bug fixes.
  </AlertDescription>
</Alert>

Description Only

<Alert>
  <AlertDescription>
    This one has a description only. No title. No icon.
  </AlertDescription>
</Alert>

Component Structure

// Alert container — CSS Grid layout
// Icon, title, and description are direct children (no wrapper divs)
<div
  role="alert"
  className="grid gap-0.5 rounded-lg border px-2.5 py-2 text-left text-sm
    has-[>svg]:grid-cols-[auto_1fr] has-[>svg]:gap-x-2
    *:[svg]:row-span-2 *:[svg]:translate-y-0.5 *:[svg]:text-current
    *:[svg:not([class*='size-'])]:size-4
    has-data-[slot=alert-action]:pr-18
    w-full relative group/alert
    bg-card text-card-foreground"
>
  {/* Icon — direct child, grid handles positioning */}
  <CircleCheck className="size-4" />

  {/* AlertTitle */}
  <div data-slot="alert-title" className="font-medium group-has-[>svg]/alert:col-start-2">
    {title}
  </div>

  {/* AlertDescription */}
  <div data-slot="alert-description" className="text-muted-foreground text-sm text-balance md:text-pretty">
    {description}
  </div>

  {/* AlertAction (optional) — absolute positioned */}
  <div data-slot="alert-action" className="absolute top-2 right-2">
    <Button size="xs">Action</Button>
  </div>
</div>

Destructive variant differences

// Container: text-destructive instead of text-card-foreground
className="... text-destructive bg-card
  *:data-[slot=alert-description]:text-destructive/90
  *:[svg]:text-current"

Accessibility

• Static container component — not built on a Radix interactive primitive
• Uses role="alert" for important messages (announced immediately by screen readers)
• No keyboard interaction needed (static content)
• Ensure decorative icons have aria-hidden="true"

Gotchas

See Also

• Related Components: Alert Dialog (blocking confirmation), Sonner (toast notifications)
• Patterns: Component Match

Figma Reference

View in Figma

Last updated: February 9, 2026