Banner

Banner carries a message about the page or section it appears in. It sits in the layout rather than floating above it, so it suits information the reader should see in context — not transient confirmations.

Layouts

Message

<Banner>Your API keys rotate on the first of each month.</Banner>

With icon

<Banner icon={<InfoIcon />}>
Deploys are paused while we upgrade the build fleet.
</Banner>

The banner sizes the icon and aligns it to the first line of text, so pass an icon from the set without a size class.

With action

<Banner button={<Button>Learn More</Button>}>
Usage this month is approaching your plan limit.
</Banner>

The button slot receives its variant and size from the banner through context, so pass a plain Button and let the banner style it. One action only — a banner with two competing actions is a dialog that has not admitted it yet.

With icon

<Banner icon={<InfoIcon />}>
Your API keys rotate on the first of each month.
</Banner>

icon sits before the message and lines up with its first line of text. Pass title to add a heading above the message, in this layout or the illustrated one.

With illustration

<Banner
title="Get started with Builder Code"
illustration={<BuilderCodeIllustration />}
button={<Button>Get Started</Button>}
>
Tag transactions with your unique codes to appear on leaderboards and qualify for future rewards.
</Banner>

Pass illustration to switch to the illustrated layout: title and the description (children) sit on the start side with a primary action, and the artwork fills the end side behind them. Use it for a feature introduction that earns more room than a one-line message. The artwork is decorative, so it is hidden from assistive technology and drops away on narrow containers, leaving the text and action.

Dismissable

const [open, setOpen] = useState(true);
const headingRef = useRef<HTMLHeadingElement>(null);

{open && (
<Banner
  button={<Button arrow>Learn More</Button>}
  onDismiss={() => {
    setOpen(false);
    headingRef.current?.focus();
  }}
>
  Trade, lend, and borrow stocks 24/7 on Base.
</Banner>
)}
<h3 ref={headingRef} tabIndex={-1}>Recent deploys</h3>

Pass onDismiss to add a close button at the banner's end edge. It works in both layouts. The banner does not hide itself: keep the open state in your app, remove the banner in onDismiss, and remember the choice if it should stay dismissed on the next visit. The close button is named "Dismiss banner"; pass dismissLabel to name it after the message, for example "Dismiss stocks announcement", when a page has more than one.

Anything else about the banner's lifecycle belongs in your app, not in Banner. The base.org announcement bar is a dismissable banner whose app rotates the message on a timer and pins the bar to the top of the page. If you rotate messages, give the reader a way to pause them and stop rotating under reduced motion.

Only make a banner dismissable when the reader can safely ignore the message. Information they need to finish a task should stay until the task is done.

When to use

Use Banner for a message about the page or section it sits in, with at most one action.

Use something else when:

• The message is the state of a resource. Use Status.
• The reader must respond before they continue. Use Dialog.
• It confirms an action the reader just took. Show a transient message near the control they used; BDS does not ship one yet.

Usage

Banner has no severity variants. When the message is about the state of a resource rather than the page, Status is the component that carries that meaning.

Props

Accessibility

Banner renders a plain div, so content present on load is read in document order. If you insert one in response to an event, give its container role="status" so the message is announced without moving focus.

Dismissing

The close button is a React Aria button, so it is reachable with Tab and activates with Enter or Space. Its glyph is decorative and its accessible name comes from dismissLabel ("Dismiss banner" by default).

When the banner is removed, the focused close button goes with it, and the browser drops focus to the top of the document. Banner does not move focus for you, because only the page knows what comes next. In onDismiss, move focus to the element that follows the banner, such as the heading of the region it described (give a non-interactive target tabIndex={-1}), so keyboard and screen reader users keep their place.