Alert Banner

Description

AlertBanner is a compound component that renders a <div role="alert"> spanning the width of its container. It is built from a root plus sub-parts (AlertBannerContent, AlertBannerHeading, AlertBannerIcon, AlertBannerDescription, AlertBannerActions, AlertBannerClose) so you compose the exact layout you need: an optional badge, an icon, a message, action buttons, and a dismiss control.

Reach for it for messages that sit above the content rather than inside it: a workspace-wide notice at the top of the app, a subscription warning, a feature announcement, or a global error state. The horizontal layout fills a page header; the vertical layout fits narrow surfaces like a sidebar card.

Don't use it for inline form validation, where the message belongs next to a field (use Field or InlineAlert). Don't use it for transient feedback that should auto-dismiss (use Toast). For a passive status label inside content, use Badge.

AlertBanner manages its own visibility. Adding an AlertBannerClose is all dismissal needs: the root holds the dismissed state, animates a collapse, and unmounts itself. There is no open prop and you should not conditionally render the banner to hide it. Use onDismiss to react once it has closed, for example to persist a "don't show again" flag.

Installation

pnpm dlx @create-ui/cli add alert-banner

Anatomy

AlertBanner provides a context that hands variant, appearance, layout, and size down to its sub-parts, and wires AlertBannerClose to the dismiss animation.

<AlertBanner>
  <AlertBannerContent>
    <Badge /> {/* optional, sits beside the heading */}
    <AlertBannerHeading>
      <AlertBannerIcon />
      <AlertBannerDescription />
    </AlertBannerHeading>
  </AlertBannerContent>
  <AlertBannerActions />
  <AlertBannerClose />
</AlertBanner>

The optional Badge is a sibling of AlertBannerHeading inside AlertBannerContent, not nested in the heading. AlertBannerActions and AlertBannerClose are direct children of AlertBanner.

Usage

import {
  AlertBanner,
  AlertBannerContent,
  AlertBannerDescription,
  AlertBannerHeading,
  AlertBannerIcon,
} from "@/components/ui/alert-banner"

<AlertBanner variant="primary">
  <AlertBannerContent>
    <AlertBannerHeading>
      <AlertBannerIcon>
        <RiFlashlightFill />
      </AlertBannerIcon>
      <AlertBannerDescription>
        Heads up, something changed
      </AlertBannerDescription>
    </AlertBannerHeading>
  </AlertBannerContent>
</AlertBanner>

Examples

Every example is a Pro preview (marked with a Pro badge). The API is the same across them; only the props change.

Variants

variant sets the semantic color. Seven options cover product intent (primary), status tones (danger, success, info, warning), an idle tone (away), and neutral for plain announcements.

Appearance

appearance controls fill weight. default is a quiet surface with a bottom border, solid is a high-contrast filled bar, soft is a tinted background, and inverse flips to the strongest surface.

Sizes

size scales the body text and icon, and in the horizontal layout it also sets the bar height (md is taller, sm is tighter for secondary notices). In the vertical layout the padding is fixed, so size only changes the type and icon. sm is the default. The preview shows both layouts at each size.

Layout

layout switches between the full-width horizontal bar and a stacked vertical card for narrow surfaces.

With Actions

Wrap buttons in AlertBannerActions to offer follow-up actions next to the message. neutral-light buttons read well on the default and soft appearances; switch to soft or inverse-solid buttons on solid and inverse banners so they hold contrast.

Minimal

Drop the badge and actions for a bare icon, message, and close button. Useful for terse status lines.

Accessibility

The root sets role="alert", an assertive live region. AlertBannerClose renders a CloseButton, which is a real focusable <button> with a built-in aria-label.

ARIA notes:

• Because role="alert" is assertive, a live region only announces content that is added or changed after the page loads. A banner already present on first render is not announced; render it in response to an event when you need it spoken.
• Assertive announcements interrupt the user, which suits errors and outages but is loud for purely promotional copy. The role is fixed, so reserve the banner for messages that warrant it.
• AlertBannerClose wraps CloseButton, which already provides aria-label="Close", so you don't add your own.
• The dismiss animation runs on a wrapper element; onDismiss fires only after the collapse transition completes.
• If a banner conveys meaning through its icon or color alone, make sure AlertBannerDescription still carries the message in text.

Styling

Tailwind override: pass className to merge Tailwind classes with the component's CVA classes (via cn()):

<AlertBanner className="w-[390px]" layout="vertical">
  <AlertBannerContent>{/* ... */}</AlertBannerContent>
</AlertBanner>

Data slots and attributes: the component sets these for CSS targeting:

• data-slot="alert-banner-wrapper" on the animated outer wrapper, with data-dismissed set while collapsing.
• data-slot="alert-banner" on the root, with data-variant, data-appearance, data-layout, and data-size.
• data-slot="alert-banner-inner" on the inner flex container.
• data-slot="alert-banner-content" on the content wrapper.
• data-slot="alert-banner-heading" on the icon + description row.
• data-slot="alert-banner-icon" on the icon wrapper.
• data-slot="alert-banner-description" on the message text.
• data-slot="alert-banner-actions" on the actions wrapper.
• data-slot="alert-banner-close" on the dismiss button.

Target a specific state in CSS:

[data-slot="alert-banner"][data-appearance="solid"] {
  /* ... */
}

Related Components

• Inline Alert: use this for a contained callout inside content, not a full-width bar.
• Toast: use this for transient, auto-dismissing feedback that stacks in a corner.
• Badge: use this for a passive status label sitting inline with content.
• Close Button: the dismiss control AlertBannerClose is built on; use it standalone elsewhere.

API Reference

AlertBanner

Root container that owns the dismiss state and provides the variant context. Renders <div role="alert"> and extends React.ComponentProps<"div">, so standard div attributes (id, aria-*, etc.) are accepted.

Props

Variants

AlertBannerContent

Wraps the badge, heading, and description into the content column. Extends React.ComponentProps<"div">.

Props

AlertBannerHeading

Row that pairs the icon with the description. Extends React.ComponentProps<"div">.

Props

AlertBannerIcon

Icon wrapper that sizes and colors the icon from the banner context. Renders a <span> and extends React.ComponentProps<"span">.

Props

AlertBannerDescription

The message text. Renders a <p> and extends React.ComponentProps<"p">.

Props

AlertBannerActions

Container for follow-up action buttons. Extends React.ComponentProps<"div">.

Props

AlertBannerClose

Dismiss control wired to the banner's collapse animation. It is absolutely positioned in the top-right corner, so the heading reserves space for it rather than wrapping around it. Extends React.ComponentProps<typeof CloseButton>, so every CloseButton prop is accepted. When you leave them unset, the defaults adapt to the banner: variant becomes inverse on solid and inverse banners (otherwise neutral), size becomes sm in the vertical layout (otherwise lg), appearance defaults to soft, and shape to pill.

Props