Choose a version:

Banner

The banner component highlights important information or required actions prominently within the interface. Use banner to communicate statuses, provide feedback, draw attention to critical updates, or guide users toward necessary actions.

Banners support multiple tones to convey urgency levels, optional actions for next steps, and can be positioned contextually within sections or page-wide at the top. For inline status indicators on individual items, use badge.

Support

Targets (24)

Supported targets

Anchor to PropertiesProperties

Configure the following properties on the banner component.

Anchor to collapsible collapsible boolean Default: false: Whether the banner content can be collapsed and expanded by the user. A collapsible banner conceals child elements initially, allowing the user to expand the banner to reveal them.
Anchor to dismissible dismissible boolean Default: false: Whether the banner displays a close button that allows users to dismiss it.

When the close button is pressed, the dismiss event will fire, then hidden will be set to true, any animation will complete, and the afterhide event will fire.
Anchor to heading heading string Default: '': The heading text displayed at the top of the banner to summarize the message or alert.
Anchor to hidden hidden boolean Default: false: Controls whether the banner is visible or hidden.

When using a controlled component pattern and the banner is dismissible, update this property to true when the dismiss event fires.

You can hide the banner programmatically by setting this to true even if it's not dismissible.
Anchor to id id string: A unique identifier for the element. Use this to reference the element in JavaScript, link labels to form controls, or target specific elements for styling or scripting.
Anchor to tone tone 'info' | 'auto' | 'success' | 'warning' | 'critical' Default: 'auto': The semantic meaning and color treatment of the component. The banner is a live region and the type of status is dictated by the tone selected.

info: Informational content or helpful tips.

auto: Automatically determined based on context.

success: Positive outcomes or successful states.

warning: Important warnings about potential issues.

critical: Urgent problems or destructive actions.

The critical tone creates an assertive live region that is announced by screen readers immediately. The info, success, and warning tones create an informative live region that is announced by screen readers after the current message.

Anchor to EventsEvents

The banner component provides event callbacks for handling user interactions. Learn more about handling events.

Anchor to afterhide afterhide <typeof tagName>: A callback that fires when the banner has fully hidden, including after any hide animations have completed.

The hidden property is true when this event fires.
Anchor to dismiss dismiss <typeof tagName>: A callback that fires when the banner is dismissed by the user clicking the close button.

This doesn't fire when setting hidden manually.

The hidden property is false when this event fires.

CallbackEventListener

A typed event listener for custom element events. The listener receives a `CallbackEvent` with the correct `currentTarget` type for the associated custom element tag.

(EventListener & {
      (event: CallbackEvent<TTagName, TEvent>): void;
    }) | null

CallbackEvent

An event type that narrows the `currentTarget` to the specific HTML element associated with the custom element tag. This provides type-safe event handling in callback listeners.

TEvent & {
  currentTarget: HTMLElementTagNameMap[TTagName];
}

Anchor to ExamplesExamples

Anchor to Display a basic notificationDisplay a basic notification

Display a basic notification to the customer. This example renders an s-banner with an info tone and a heading to communicate a free shipping promotion.

Display a basic notification

An informational banner with a blue info icon and the text Free shipping on all orders.

html

<s-banner heading="Free shipping on all orders." tone="info"></s-banner>

Anchor to Show a dismissible bannerShow a dismissible banner

Let customers dismiss informational banners after reading them. This example uses the dismissible property to add a close button that hides the banner when pressed.

html

<s-banner heading="Your next subscription order ships on March 15." tone="info" dismissible></s-banner>

Anchor to Present a collapsible warningPresent a collapsible warning

Use a collapsible banner to show a warning title with additional details hidden by default. This example warns about an expiring payment method and reveals instructions when expanded.

html

<s-banner heading="Your subscription payment method expires soon" tone="warning" collapsible>

<s-text>Update your payment method before April 1 to avoid interruption to your subscription.</s-text>

</s-banner>

Anchor to Best practicesBest practices

Use banners sparingly: Too many banners distract customers from the main content. Reserve them for the most important information.
Place banners contextually: Display banners at the top of a page or section, below the relevant header. If a banner relates to specific content, place it near that content.
Include a next step when possible: Add a button with a clear action so customers know what to do after reading the message.
Make banners dismissible unless critical: Customers should be able to dismiss informational banners. Keep critical banners persistent until the issue is resolved.
Match tone to urgency: Use info for general updates, warning for issues needing attention, success for confirmations, and critical for problems that block progress.

Was this page helpful?