Skip to Content
Dashflow Logo

Alert Component

A comprehensive guide to using the Alert component with examples, props, and best practices.

Overview

The Alert component is a wrapper around @dashflowx/core that provides a consistent way to display notifications, warnings, and informational messages. It leverages the existing, tested components from the core package while maintaining a clean API. The component supports multiple variants, sizes, and configurations to accommodate different types of notifications and design requirements.

Key Features:

  • Built on @dashflowx/core: Uses the existing, tested Alert component
  • Flexible prefix support: Accepts both JSX elements and strings for icons
  • Automatic icon fallback: Provides default icons when no prefix is specified
  • Consistent styling: Maintains visual consistency across all variants
  • Type-safe: Full TypeScript support with proper prop validation

Icons are controlled through the prefix prop, giving you full control over the visual representation. When using Markdoc tags, you can pass string prefixes (like "✓", "⚠", "ℹ") and they will be automatically converted to proper icon elements.

Basic Usage

import { Alert } from '@dashflowx/core'
import { InformationCircleIcon } from '@heroicons/react/24/outline'


export default function AlertExample() {
  return (
    <Alert 
      variant="basic"
      title="Information"
      description="This is an informational alert message that provides important information to the user."
      prefix={<InformationCircleIcon className="w-5 h-5 text-gray-600" />}
    />
  )
}

Preview:

Variants

The Alert component supports multiple variants to convey different types of messages. Each variant has distinct colors and styling:

Basic Alert

Default alert style with neutral colors.

import { InformationCircleIcon } from '@heroicons/react/24/outline'


<Alert 
  variant="basic"
  title="Information"
  description="This is a basic informational alert with neutral styling."
  prefix={<InformationCircleIcon className="w-5 h-5 text-gray-600" />}
/>

Preview:

Success Alert

Used for successful operations and positive feedback.

import { CheckCircleIcon } from '@heroicons/react/24/outline'


<Alert 
  variant="success"
  title="Success"
  description="Your action was completed successfully. The changes have been saved."
  prefix={<CheckCircleIcon className="w-5 h-5 text-green-600" />}
/>

Preview:

Warning Alert

Used for warnings and cautionary messages.

import { ExclamationTriangleIcon } from '@heroicons/react/24/outline'


<Alert 
  variant="warning"
  title="Warning"
  description="Please review your input before proceeding. Some fields may need attention."
  prefix={<ExclamationTriangleIcon className="w-5 h-5 text-yellow-600" />}
/>

Preview:

Error Alert

Used for errors and critical issues.

import { XCircleIcon } from '@heroicons/react/24/outline'


<Alert 
  variant="error"
  title="Error"
  description="Something went wrong. Please check your connection and try again."
  prefix={<XCircleIcon className="w-5 h-5 text-red-600" />}
/>

Preview:

Info Alert

Used for informational messages and updates.

import { InformationCircleIcon } from '@heroicons/react/24/outline'


<Alert 
  variant="info"
  title="Update Available"
  description="A new version is available for download. Click here to update."
  prefix={<InformationCircleIcon className="w-5 h-5 text-blue-600" />}
/>

Preview:

Sizes

The Alert component supports three different sizes:

Small (sm)

Compact size for inline alerts.

import { CheckCircleIcon } from '@heroicons/react/24/outline'


<Alert 
  variant="success"
  size="sm"
  title="Success"
  description="Operation completed."
  prefix={<CheckCircleIcon className="w-4 h-4 text-green-600" />}
/>

Medium (md) - Default

Standard size for most use cases.

import { InformationCircleIcon } from '@heroicons/react/24/outline'


<Alert 
  variant="info"
  size="md"
  title="Information"
  description="This is the default medium size."
  prefix={<InformationCircleIcon className="w-5 h-5 text-blue-600" />}
/>

Large (lg)

Prominent size for important messages.

import { ExclamationTriangleIcon } from '@heroicons/react/24/outline'


<Alert 
  variant="warning"
  size="lg"
  title="Important Notice"
  description="This is a large, prominent alert."
  prefix={<ExclamationTriangleIcon className="w-6 h-6 text-yellow-600" />}
/>

Size Examples Preview:

Small Size:

Medium Size:

Large Size:

Props

PropTypeDefaultDescription
variant'basic' | 'success' | 'warning' | 'error' | 'info''basic'The visual style variant of the alert
size'sm' | 'md' | 'lg''md'The size of the alert
titlestring | JSX.Element-The title/heading of the alert
descriptionstring | JSX.Element-The main content/description of the alert
prefixJSX.Element-Custom icon or prefix element (controls icon display)
classNamestring-Additional CSS classes for the alert container
titleClassNamestring-Additional CSS classes for the alert title
descriptionClassNamestring-Additional CSS classes for the alert description
childrenReact.ReactNode-Alternative to description for content
dismissiblebooleanfalseWhether the alert can be dismissed
onDismiss() => void-Callback when alert is dismissed

Examples

Alert with Custom Icon

import { CheckCircleIcon } from '@heroicons/react/24/outline'


<Alert 
  variant="success"
  title="Success"
  description="Your changes have been saved successfully."
  prefix={<CheckCircleIcon className="w-5 h-5 text-green-600" />}
/>

Preview:

Alert without Icon

<Alert 
  variant="info"
  title="No Icon"
  description="This alert doesn't show an icon."
/>

Preview:

Dismissible Alert

import { useState } from 'react'
import { Alert } from '@dashflowx/core'
import { CheckCircleIcon } from '@heroicons/react/24/outline'


export default function DismissibleAlertExample() {
  const [showAlert, setShowAlert] = useState(true)
  
  if (!showAlert) return null
  
  return (
    <Alert 
      variant="success"
      title="Success"
      description="Your changes have been saved successfully."
      prefix={<CheckCircleIcon className="w-5 h-5 text-green-600" />}
      dismissible={true}
      onDismiss={() => setShowAlert(false)}
    />
  )
}

Preview:

Alert with JSX Content

import { ExclamationTriangleIcon } from '@heroicons/react/24/outline'


<Alert 
  variant="warning"
  title="Complex Content"
  description={
    <div>
      <p>This alert contains JSX content with multiple elements:</p>
      <ul className="mt-2 list-disc list-inside">
        <li>Formatted text</li>
        <li>Lists and other elements</li>
        <li>Custom styling</li>
      </ul>
    </div>
  }
  prefix={<ExclamationTriangleIcon className="w-5 h-5 text-yellow-600" />}
/>

Preview:

Alert with Custom Styling

import { InformationCircleIcon } from '@heroicons/react/24/outline'


<Alert 
  variant="info"
  title="Custom Styling"
  description="This alert has custom styling applied."
  prefix={<InformationCircleIcon className="w-5 h-5 text-blue-600" />}
  className="border-purple-300 bg-purple-50 shadow-lg"
  titleClassName="text-purple-800 font-bold text-lg"
  descriptionClassName="text-purple-700 mt-2"
/>

Preview:

Icon Usage

The Alert component uses the prefix prop to control icon display. This gives you complete control over the icon appearance:

Using Heroicons

import { 
  CheckCircleIcon, 
  ExclamationTriangleIcon, 
  XCircleIcon, 
  InformationCircleIcon 
} from '@heroicons/react/24/outline'


// Success alert with checkmark
<Alert 
  variant="success"
  title="Success"
  description="Operation completed successfully."
  prefix={<CheckCircleIcon className="w-5 h-5 text-green-600" />}
/>


// Warning alert with triangle
<Alert 
  variant="warning"
  title="Warning"
  description="Please review your input."
  prefix={<ExclamationTriangleIcon className="w-5 h-5 text-yellow-600" />}
/>


// Error alert with X circle
<Alert 
  variant="error"
  title="Error"
  description="Something went wrong."
  prefix={<XCircleIcon className="w-5 h-5 text-red-600" />}
/>


// Info alert with info circle
<Alert 
  variant="info"
  title="Information"
  description="Here's some useful information."
  prefix={<InformationCircleIcon className="w-5 h-5 text-blue-600" />}
/>

Success:

Warning:

Error:

Information:

Using Custom SVG Icons

const CustomIcon = () => (
  <svg className="w-5 h-5" fill="currentColor" viewBox="0 0 20 20">
    <path d="M10 18a8 8 0 100-16 8 8 0 000 16zM9 9a1 1 0 000 2v3a1 1 0 001 1h1a1 1 0 100-2v-3a1 1 0 00-1-1H9z" />
  </svg>
)


<Alert 
  variant="info"
  title="Custom Icon"
  description="This alert uses a custom SVG icon."
  prefix={<CustomIcon />}
/>

Preview:

Using Emoji Icons

<Alert 
  variant="success"
  title="Success"
  description="Your action was completed successfully."
  prefix={<span className="text-lg">🎉</span>}
/>

Preview:

Composition API

The Alert component also supports a composition pattern using sub-components:

import { Alert, AlertTitle, AlertDescription } from '@dashflowx/core'


<Alert variant="success">
  <AlertTitle>Success</AlertTitle>
  <AlertDescription>
    Your action was completed successfully.
  </AlertDescription>
</Alert>

Preview:

Accessibility

The Alert component includes comprehensive accessibility features:

  • ARIA role: Uses role="alert" for screen readers
  • ARIA live: Uses aria-live="polite" for dynamic content
  • Semantic structure: Proper heading hierarchy with title and description
  • Screen readers: Properly announces alert content and importance
  • Focus management: Dismissible alerts include proper focus handling
  • Keyboard navigation: Full keyboard support for dismissible alerts

Best Practices

Choose Appropriate Variants Use variants that match the message type and user expectations.

import { CheckCircleIcon, ExclamationTriangleIcon, XCircleIcon } from '@heroicons/react/24/outline'


// ✅ Good - Success for completed actions
<Alert 
  variant="success" 
  title="Payment Complete" 
  description="Your order has been processed." 
  prefix={<CheckCircleIcon className="w-5 h-5 text-green-600" />}
/>


// ✅ Good - Warning for potential issues
<Alert 
  variant="warning" 
  title="Session Expiring" 
  description="Your session will expire in 5 minutes." 
  prefix={<ExclamationTriangleIcon className="w-5 h-5 text-yellow-600" />}
/>


// ✅ Good - Error for actual problems
<Alert 
  variant="error" 
  title="Upload Failed" 
  description="The file could not be uploaded." 
  prefix={<XCircleIcon className="w-5 h-5 text-red-600" />}
/>

Use Meaningful Icons Choose icons that clearly represent the alert's purpose.

// ✅ Good - Clear icon choice
<Alert 
  variant="success"
  title="Success"
  prefix={<CheckCircleIcon className="w-5 h-5 text-green-600" />}
  description="Your profile has been updated."
/>


// ✅ Good - Appropriate warning icon
<Alert 
  variant="warning"
  title="Warning"
  prefix={<ExclamationTriangleIcon className="w-5 h-5 text-yellow-600" />}
  description="Please review your settings before proceeding."
/>

Clear and Actionable Messages Provide clear, actionable information in your alerts.

import { XCircleIcon } from '@heroicons/react/24/outline'


// ❌ Bad - Vague message
<Alert 
  variant="error" 
  title="Error" 
  description="Something went wrong." 
  prefix={<XCircleIcon className="w-5 h-5 text-red-600" />}
/>


// ✅ Good - Specific and actionable
<Alert 
  variant="error" 
  title="Upload Failed" 
  description="The file 'document.pdf' could not be uploaded. Please check the file size and try again." 
  prefix={<XCircleIcon className="w-5 h-5 text-red-600" />}
/>

Consistent Icon Usage Maintain consistent icon usage throughout your application.

// ✅ Good - Consistent icon patterns
<Alert 
  variant="success"
  prefix={<CheckCircleIcon className="w-5 h-5 text-green-600" />}
  title="Success"
  description="Operation completed."
/>


<Alert 
  variant="warning"
  prefix={<ExclamationTriangleIcon className="w-5 h-5 text-yellow-600" />}
  title="Warning"
  description="Please review your input."
/>

Common Use Cases

Form Validation

<Alert 
  variant="error"
  title="Validation Error"
  description="Please fill in all required fields before submitting the form."
  prefix={<XCircleIcon className="w-5 h-5 text-red-600" />}
/>

Success Notifications

<Alert 
  variant="success"
  title="Account Created"
  description="Your account has been successfully created. You can now log in."
  prefix={<CheckCircleIcon className="w-5 h-5 text-green-600" />}
/>

System Status

<Alert 
  variant="warning"
  title="System Maintenance"
  description="Scheduled maintenance will occur tonight from 2:00 AM to 4:00 AM EST."
  prefix={<ExclamationTriangleIcon className="w-5 h-5 text-yellow-600" />}
/>

Feature Announcements

<Alert 
  variant="info"
  title="New Features Available"
  description="Check out our latest updates including dark mode and improved search."
  prefix={<InformationCircleIcon className="w-5 h-5 text-blue-600" />}
  dismissible={true}
/>

Customization

Custom Color Schemes

You can override the default colors using CSS classes:

import { InformationCircleIcon } from '@heroicons/react/24/outline'


<Alert 
  variant="basic"
  title="Custom Colors"
  description="This alert uses custom colors."
  prefix={<InformationCircleIcon className="w-5 h-5 text-purple-600" />}
  className="border-purple-300 bg-purple-50 text-purple-800"
  titleClassName="text-purple-900"
  descriptionClassName="text-purple-700"
/>

Custom Icon Styling

Customize your icons with additional styling:

<Alert 
  variant="success"
  title="Custom Icon Styling"
  description="This icon has custom styling applied."
  prefix={
    <CheckCircleIcon className="w-6 h-6 text-green-600 bg-green-100 p-1 rounded-full" />
  }
/>

Responsive Design

The Alert component works well across all screen sizes:

import { InformationCircleIcon } from '@heroicons/react/24/outline'


<Alert 
  variant="info"
  size="sm"
  className="md:size-md lg:size-lg"
  title="Responsive Alert"
  description="This alert adapts to different screen sizes."
  prefix={<InformationCircleIcon className="w-4 h-4 text-blue-600" />}
/>
  • Toast: For temporary notifications
  • Modal: For important confirmations
  • Banner: For persistent site-wide messages
  • Callout: For highlighted information blocks
  • Notification: For system notifications

API Reference

For the complete API reference and advanced usage patterns, see the Alert API documentation.

Edit this page on GitHub
previousAccordion