Preview
Design guidance
Use a banner for a notice that affects the current task. Keep its message short. Set the tone to match the message. Keep action results and dismissal state in the caller.
Banners fit their content by default. Use width="fill" to span the available container width while keeping rounded corners. For an announcement, use placement="top" or placement="bottom". Announcement placement sets full width and square corners, and sticks to that edge of the nearest scroll container. Place it in a container that spans the page to reach both screen edges. Use native style or className for a sticky offset below an existing header.
Use Button variant="solid" for a status-colored action or variant="ghost" for a quiet action. Banner supplies context through the shared theme roles. Ghost hover and pressed fills stay transparent; the theme controls their strength through --surface-hover-opacity and --surface-active-opacity. Button owns focus, disabled, loading, and input behavior.
Installation
Basic usage
Structures
The icon sits on the left by default. iconPosition="top" places it above the text. Actions sit on the right by default. actionPosition="bottom" moves them below the text and puts the close button at the end of the same row. A close-only banner keeps its close button at the top right.
Examples
Basic banner
Text only banner
Use a title and message without a leading icon or controls.
Removable banner
Add a close icon button. It aligns with the first title line. The caller removes the notice after dismissal.
Action banner
Add a Button in the action slot. Its result remains caller-owned.
Description only
Omit the title for a short message. The leading icon and message align vertically at the center.
Close without actions
A close-only notice keeps the close control beside the first text line, including when actionPosition="bottom" is set.
Dismissed state
Notice dismissed.
Status banner
Warning
Success
Danger
Primary
Ghost action
Use a ghost Button for less emphasis. Its transparent hover fill lets the status background show through.
Layout variation
Bottom actions
Place the action and close control below the text. Keyboard order follows the action, then the close control.
Top icon
Place the icon above the text and keep the actions on the right when space permits.
Top icon and bottom actions
Combine both placement options with a ghost action.
Multiple actions
Compose Buttons in actions. They wrap when space is limited.
Without leading icon
Long content
Width behavior
Content width
The default banner fits its message and controls. Long content wraps within the available width.
Fill width
Fill the containing area and keep the banner's rounded corners. This setting does not change its position.
Special use cases
Header and footer announcements
The header announcement stays at the top. The footer announcement stays at the bottom. Both span the preview with square corners. Skeleton represents the page content between them. Scroll inside the preview or dismiss either banner independently.
API reference
| Prop | Type | Default | Description |
|---|---|---|---|
tone | 'neutral' | 'primary' | 'success' | 'warning' | 'danger' | neutral | Sets the notice tone and solid action color. |
title | ReactNode | Optional regular-weight notice heading. | |
children | ReactNode | Notice message, set at12px by default. | |
icon | ReactNode | null | Overrides the tone icon; null hides its slot. | |
iconPosition | 'left' | 'top' | left | Places the leading icon beside or above the text. |
actions | ReactNode | Caller-owned actions. Compose canonical Button with solid or ghost variants. | |
actionPosition | 'right' | 'bottom' | right | Places actions beside or below the text. When actions are supplied, bottom placement includes the close control. |
width | 'content' | 'fill' | content | Fits the content by default. Fill spans the container and keeps rounded corners. |
placement | 'inline' | 'top' | 'bottom' | inline | Top and bottom create sticky announcements: full width, square corners, and the chosen scroll-container edge. Overrides content width. |
onDismiss | () => void | Enables a dismiss IconButton. Caller removes the notice. | |
dismissLabel | string | Dismiss | Accessible name for the close control. |
role | 'status' | 'alert' | 'note' | Sets the root role; danger defaults to alert, other tones to status. | |
id and div attributes | HTMLAttributes<HTMLDivElement> | Forwarded to the root element. |