Banner

Installation#

# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

# Add this component (its dependencies come along)
npx koalaui-cli@latest add banner

Usage#

Anatomy#

import {
  Banner,
  BannerOrnament,
  BannerIcon,
  BannerContent,
  BannerAction,
} from "@/components/ui/banner"

<Banner>
  <BannerOrnament />
  <BannerIcon />
  <BannerContent />
  <BannerAction />
</Banner>

Variants#

Soft tones tint the background from a single semantic token and color the icon, action, and message to match. The message takes a deep, tone-tinted ink (a dark blue, dark purple, ...) on light themes and lifts to a bright tint on dark ones, so it stays readable while the icon and action keep the pure hue. Every tone re-themes across light, dark, cream, and moonlight.

Solid#

Set appearance="solid" for a filled bar. Solid is designed for two theme-stable surfaces: the default inverse bar (flips with the theme) and the brand accent bar. The soft tones stay tinted because the hue tokens shift lightness per theme.

Festive#

Set appearance="festive" for a playful celebration bar: a flat, saturated fill behind white text, the natural home for launches, milestones, and holidays. It ignores the tone variant. Recolor the bar by overriding one CSS variable, --banner-festive-via, with a brand or flag color. Keep it deep and saturated so the white text stays legible across every theme.

Interactive (confetti)#

Add confetti to a festive bar to make it playful: it bursts once on mount and again on every click. The icon pops on the mount burst only, so clicking showers confetti while the icon stays still. The pieces are themed by the --banner-confetti-* tokens, which derive from the festive palette, so they re-tint with it (recolor the bar and the confetti follows). It is decorative and fully honors reduced-motion. Click the bars below.

Ornaments#

Drop a BannerOrnament in to peek a decorative flag, mascot, or emoji in from an edge. It clips to the bar and sits behind the message, tilting away from its side. Below, two Venezuela flags (rounded 16px, not circular) peek from the corners of a flat solid bar, with the confetti tinted to the flag's yellow and red. The flag itself is any element you like, sized and rounded however you want.

Alignment#

The default align="center" centers the message. Switch to align="between" to pin the message left and the action right, the natural home for a Button CTA.

Shape#

shape sets the bar's footprint. The default "bar" runs edge to edge, the classic strip atop a page. "inset" draws the same bar as a rounded card that sits inside the page gutter, above the navbar: place it in a SectionContainer (or any gutter) and it takes that width, its inner row trading the page-width cap for a card interior and a step more height.

Size#

size sets the strip's own height and side padding."md" (default) is the page bar, with the 24px page gutter."sm" is a compact strip for a panel, a tablet screen or the head of a card: 12px sides, a 32px row, the type a step down and a smaller close button, and no page-width cap. Use it instead of reaching into the inner row with selectors.

Dismissible#

Set dismissible to render a trailing close button. Uncontrolled by default (the banner hides itself); pass open / onOpenChange to control it, and always give a descriptive dismissLabel.

As child action#

Use asChild on BannerAction to render the link styles onto a framework link (e.g. Next.js <Link>) via Radix Slot, keeping client-side navigation.

API reference#

FAQ#