Custom Headless Alert Banner

A fully accessible, customizable alert banner component built with React and Tailwind CSS. Meets WCAG 2.1 AA standards.

Installation

npm install custom-headless-alert-banner

Usage

import { AlertBanner } from "custom-headless-alert-banner";

function App() {
  const handleClose = () => {
    console.log("Alert closed");
  };

  return (
    <div>
      {/* Success Alert */}
      <AlertBanner
        type="success"
        message="Your changes have been saved successfully!"
        dismissible={true}
        onClose={handleClose}
      />

      {/* Error Alert */}
      <AlertBanner
        type="error"
        message="An error occurred while saving your changes."
        dismissible={true}
        onClose={handleClose}
      />

      {/* Info Alert */}
      <AlertBanner
        type="info"
        message="Please review your information before submitting."
      />

      {/* Warning Alert */}
      <AlertBanner
        type="warning"
        message="Your session will expire in 5 minutes."
        dismissible={true}
        onClose={handleClose}
      />
    </div>
  );
}

Props

| Prop | Type | Required | Default | Description | | ------------- | --------------------------------------------- | -------- | ------- | ---------------------------------------------------- | | type | 'success' \| 'error' \| 'info' \| 'warning' | Yes | - | The type of alert to display | | message | string | Yes | - | The message to display in the alert | | dismissible | boolean | No | false | Whether the alert can be dismissed | | onClose | () => void | No | - | Callback function called when the alert is dismissed |

Alert Types

• Success: Green background with checkmark icon
• Error: Red background with exclamation circle icon
• Info: Blue background with information circle icon
• Warning: Yellow background with exclamation triangle icon

Styling

The component uses Tailwind CSS classes and is fully responsive. It automatically adjusts its layout and sizing based on screen size.

Accessibility

• error and warning alerts use role="alert" with aria-live="assertive" so screen readers announce them immediately
• success and info alerts use role="status" with aria-live="polite" for non-urgent announcements
• aria-atomic="true" ensures the full message is read on any update
• Type icons are marked aria-hidden="true" (decorative — meaning is conveyed by role + text)
• Dismiss button has aria-label="Dismiss alert" and a visible keyboard focus ring (focus-visible)
• Dismiss button is type="button" to prevent accidental form submission when nested in forms

Dependencies

• React 18+
• @heroicons/react
• Tailwind CSS

License

ISC