---
title: Banner
description: >-
  Highlights important status messages, warnings, or required actions so buyers
  can resolve issues or stay informed during checkout.
api_version: 2026-04
api_name: checkout-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/feedback-and-status-indicators/banner
  md: >-
    https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/feedback-and-status-indicators/banner.md
---

# Banner

The banner component highlights important information or required actions prominently within the interface. Use banners to communicate statuses, provide feedback, draw attention to critical updates, or guide buyers 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](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/feedback-and-status-indicators/badge).

### Support Targets (29)

### Supported targets

* [purchase.​checkout.​actions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/navigation#navigation-target)
* [purchase.​checkout.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/block#block-target)
* [purchase.​checkout.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#line-item-targets)
* [purchase.​checkout.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#checkout-cart-line-list-)
* [purchase.​checkout.​contact.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/information#information-target)
* [purchase.​checkout.​delivery-address.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-delivery-address-)
* [purchase.​checkout.​delivery-address.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#delivery-address-targets)
* [purchase.​checkout.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/footer#footer-target)
* [purchase.​checkout.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/header#header-target)
* [purchase.​checkout.​payment-method-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/payment#render-after-payment-methods-)
* [purchase.​checkout.​payment-method-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/payment#payment-targets)
* [purchase.​checkout.​pickup-location-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#render-after-pickup-locations-)
* [purchase.​checkout.​pickup-location-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#location-list-targets)
* [purchase.​checkout.​pickup-location-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#location-option-item-target)
* [purchase.​checkout.​pickup-point-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/pickup-points#render-after-pickup-points-)
* [purchase.​checkout.​pickup-point-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/pickup-points#pickup-points-targets)
* [purchase.​checkout.​reductions.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#checkout-reductions-after-)
* [purchase.​checkout.​reductions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#reductions-targets)
* [purchase.​checkout.​shipping-option-item.​details.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#shipping-option-item-targets)
* [purchase.​checkout.​shipping-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-shipping-option-)
* [purchase.​checkout.​shipping-option-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-shipping-options-)
* [purchase.​checkout.​shipping-option-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#shipping-option-list-targets)
* [purchase.​thank-you.​announcement.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/announcement#thank-you-announcement-)
* [purchase.​thank-you.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/block#block-target)
* [purchase.​thank-you.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/order-summary#line-item-targets)
* [purchase.​thank-you.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/order-summary#thank-you-cart-line-list-)
* [purchase.​thank-you.​customer-information.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/information#information-target)
* [purchase.​thank-you.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/footer#footer-target)
* [purchase.​thank-you.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/header#header-target)

#### Use cases

* **Shipping promotions**: Notify buyers about free shipping thresholds or delivery offers to encourage larger orders.
* **Payment warnings**: Alert buyers to payment issues or expiring payment methods that need attention.
* **Error recovery**: Guide buyers through resolving checkout errors with clear next steps and actionable buttons.
* **Discount confirmations**: Confirm that a discount code or automatic promotion has been applied successfully.

***

## Properties

Configure the following properties on the banner component.

* **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.

* **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.

* **heading**

  **string**

  **Default: ''**

  The heading text displayed at the top of the banner to summarize the message or alert.

* **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`.

* **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.

* **tone**

  **'success' | 'info' | 'auto' | '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](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role) that is announced by screen readers immediately. The `info`, `success`, and `warning` tones create an [informative live region](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/status_role) that is announced by screen readers after the current message.

### Events

The banner component provides event callbacks for handling user interactions. Learn more about [handling events](https://shopify.dev/docs/api/polaris/using-polaris-web-components#handling-events).

* **afterhide**

  **CallbackEventListener\<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.

* **dismiss**

  **CallbackEventListener\<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.

```ts
(EventListener & {
    (event: CallbackEvent<TTagName, Event> & TData): 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.

```ts
TEvent & {
    currentTarget: HTMLElementTagNameMap[TTagName];
}
```

***

## Examples

### Display a basic notification

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

## Display a basic notification

![A rendered example of the banner component](https://shopify.dev/assets/assets/images/templated-apis-screenshots/checkout-ui-extensions/2025-10/banner-default-DUI7koDV.png)

## html

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

### Warn with a dismissible banner

Present a warning buyers can dismiss. This example combines `warning` tone with `dismissible` for address verification details.

## html

```html
<s-banner
  heading="Action needed for delivery"
  tone="warning"
  dismissible
  collapsible
>
  <s-paragraph>
    We could not verify your apartment number. Update your address or confirm
    the building name so we can ship your order.
  </s-paragraph>
</s-banner>
```

### Confirm a successful action

Confirm to buyers when they successfully complete an action. This example shows an `s-banner` confirming a discount application with `tone="success"` and a short savings summary.

## html

```html
<s-banner heading="Discount applied" tone="success">
  <s-paragraph>
    Your code SAVE10 saved you $10.00 on this order.
  </s-paragraph>
</s-banner>
```

***

## Best practices

* **Use banners sparingly**: Too many banners distract buyers from completing checkout. 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](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/button) with a clear action so buyers know what to do after reading the message.
* **Make banners dismissible unless critical**: Buyers should be able to dismiss informational banners. Keep `critical` banners persistent until the issue is resolved.
* **Match tone to urgency**: The default tone is `auto`, which adapts to context. Use `info` for general updates, `warning` for issues needing attention, `success` for confirmations, and `critical` for problems that must be resolved to complete checkout.
* **Use the `critical` tone sparingly**: The `critical` tone creates an assertive live region that screen readers announce immediately. Overusing it overwhelms buyers using assistive technology.

***