Banner

A banner is a short notice that people need to read before they act: who can see a shared channel, what a delete removes, a limit they are about to reach, or that something saved. It sits inside the content of a dialog or a form, on a soft tint that says its intent. When something in one panel goes wrong, the same notice runs as a strip under the panel header instead; see Inside a panel.

跟随页面浅色深色并排

When to use

The wider the scope of a message, the further out it goes; the full table is in Feedback.

Anatomy

• Banner: the tinted container. Required. It fills the width it is given and lays out its parts by that width, so give it a width (or let it fill its parent); never w-fit, which collapses it.
• An icon: a Lucide icon as a direct child, before the text, or a Status light in its place. Banner sizes the icon 20px with 10px before the text (16px and 8px in a sm banner), keeps a light at 9px, and centers either one on the first line (A mark that leads text).
• BannerTitle: an optional bold first line.
• BannerDescription: the message. Required. An inline text action goes inside it as a TextLink variant="strong", because it sits in a sentence (TextLink).
• BannerAction: the banner's button, and Dismiss before it when the banner has one. It sits at the bottom right: at the end of the last line of text, centered on that line, while the text fits beside it on one line. With a title and a description, that line is the description's. When the text would wrap beside it, or the banner is narrower than 480px, it takes a line of its own under the text, aligned to the end. BannerAction decides this itself; don't place it. The width is a container query on the banner's content: 452px, which is a 480px banner at md (476px at sm, 484px at lg).
• BannerClose: the × of a banner that has no button. A frameless icon button at the end of the first line, centered on it, whose icon box ends on the banner's padding, like a frameless icon button at the end of a header (Alignment). Its label defaults to "Dismiss". Don't use it with BannerAction: a banner with a button closes with Dismiss. If both are there, raft-ui warns in development and puts the actions on a line of their own, so they never share the ×'s place.

Variants

The status prop sets the tint. Each intent has one icon.

跟随页面浅色深色并排

跟随页面浅色深色并排

Under 480px, as on every phone, the buttons go under the text, at the end:

跟随页面浅色深色并排

A banner with no button closes with BannerClose:

跟随页面浅色深色并排

• Use status="warning" when something goes wrong; destructive is only for consequences that cannot be undone (Color).
• raft-ui also has a neutral status="default" on fill-muted. The system's banners always state an intent, so prefer one of the four above.

Content

• Say what is happening now and what to do next (Writing, Feedback).
• Put the subject in BannerTitle and the consequence in BannerDescription: "This channel is shared with Acme" / "People and agents from Acme will see what you post here."
• Label the button with what it does, in Title Case: See Who, Retry, View Logs.

Accessibility

• Banner renders a div with role="alert" for status="destructive" and role="status" for the other intents, so a notice that isn't urgent doesn't interrupt a screen reader.
• The icon repeats the intent and is decorative. The title and description must say the intent in words.
• BannerClose is labelled "Dismiss"; pass an aria-label that names the notice when a page has more than one thing to dismiss.
• BannerClose doesn't move focus. When the banner goes, the app moves focus to the next element after where the banner was, or to the page's heading when there is none; never leave it on the document.
• Keep the parts in reading order: the icon, the title, the description with its link, then BannerAction (Dismiss, then the button) or BannerClose. Tab reaches them in that order.

Rules

• Show at most one banner in one place.
• Give at most one button, plus Dismiss before it when the banner can be dismissed, and only when there is a way out: a 32px ink-bordered button (variant="default" size="sm"). Never a pink button: a banner is not the screen's primary action.
• Put the button in BannerAction, at the bottom right, so it comes after what it acts on and ends where the eye ends, as a dialog's commit button does. A banner that can be dismissed and has a button puts Dismiss (variant="ghost" size="sm") just before the button, in the same BannerAction.
• Use BannerClose only on a banner with no button, and never put a × in BannerAction, where it reads as one of the actions.
• Don't add an ink border. A banner is a soft tint, not a sticker (Color); its edge is the container radius and a hairline.

Inside a panel

When something in one panel goes wrong (an agent won't start, the channel's settings didn't save), use PanelNotice from Panel, not a Banner. It is a region of the panel, not a card inside its content:

• Place it directly under the panel header, across the full width of the panel.
• Give it no radius and no hairline. It is closed by seams (line-seam) above and below; the one above is the panel header's.
• Line its sides up with the panel's margins (Spacing).
• Lead the text with a status pixel instead of an icon. PanelNotice keeps it at 9px and centers it on the first line, as it does an icon (A mark that leads text).
• Write one message of at most 2 lines, in PanelNoticeContent (semibold text-callout).
• Put the actions in PanelNoticeActions, on the right and centered on the first line of text: a small icon button (Copy Details) or a text button (View Logs). A 32px button doesn't make the strip taller.
• Keep the default status="warning" for something to fix; use destructive only for what cannot be undone.