--- title: Banner description: >- 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](/docs/api/app-home//web-components/feedback-and-status-indicators/badge). api_name: app-home source_url: html: >- https://shopify.dev/docs/api/app-home/web-components/feedback-and-status-indicators/banner md: >- https://shopify.dev/docs/api/app-home/web-components/feedback-and-status-indicators/banner.md --- # 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](https://shopify.dev/docs/api/app-home/web-components/feedback-and-status-indicators/badge). #### Use cases * **Important announcements:** Communicate critical information about app features or requirements. * **Error messages:** Display prominent error messages that require merchant attention. * **Success confirmations:** Show success messages for important operations like saves or sync. * **Warnings:** Alert merchants to potential issues like missing configuration or deprecated features. ## Properties Configure the following properties on the banner component. * **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 fires, then `hidden` is set to `true`, any animation completes, and the `afterhide` event fires. * **heading** **string** **Default: ''** The heading text displayed at the top of the banner. * **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`. * **tone** **"info" | "success" | "warning" | "critical" | "auto"** **Default: 'auto'** The semantic meaning and color treatment of the component. * `info`: Informational content or helpful tips. * `success`: Positive outcomes or successful states. * `warning`: Important warnings about potential issues. * `critical`: Urgent problems or destructive actions. * `auto`: Automatically determined based on context. ## Events The banner component provides event callbacks for handling user interactions. Learn more about [handling events](https://shopify.dev/docs/api/app-ui/using-web-components#handling-events). * **afterhide** **CallbackEventListener\ | null** A callback fired after the banner is hidden. * **dismiss** **CallbackEventListener\ | null** A callback fired when the banner is dismissed. ### CallbackEventListener A function that handles events from UI components. This type represents an event listener callback that receives a \`CallbackEvent\` with a strongly-typed \`currentTarget\`. Use this for component event handlers like \`click\`, \`focus\`, \`blur\`, and other DOM events. ```ts (EventListener & { (event: CallbackEvent): void; }) | null ``` ### CallbackEvent An event object with a strongly-typed \`currentTarget\` property that references the specific HTML element that triggered the event. This type extends the standard DOM \`Event\` interface and ensures type safety when accessing the element that fired the event. ```ts Event & { currentTarget: HTMLElementTagNameMap[T]; } ``` ## Slots The banner component supports slots for additional content placement within the banner. Learn more about [using slots](https://shopify.dev/docs/api/app-ui/using-web-components#slots). * **children** **HTMLElement** The main message content displayed within the banner component, providing important information or guidance to users. * **secondary-actions** **HTMLElement** Action buttons displayed at the bottom of the banner that let users respond to the message. Accepts up to two button components with `variant="secondary"` or `variant="auto"`. Examples ### Examples * #### Add a dismissible info banner ##### Description Create an informational banner with a heading and body text. This example shows a basic banner communicating a status update that merchants can dismiss. ##### html ```html This order was archived on March 7, 2017 at 3:12pm EDT. ``` * #### Create a warning banner with buttons for next steps ##### Description Use a warning-toned banner with secondary action \[buttons]\(/docs/api/{API\_NAME}/{API\_VERSION}/web-components/actions/button) to highlight a problem and give merchants clear next steps. This example shows a shipping weight issue with links to review products and access a setup guide. ##### html ```html Products without weights may show inaccurate shipping rates, leading to checkout abandonment. Review products Setup guide ``` * #### Alert merchants to critical issues requiring action ##### Description Use a critical-toned banner to signal an urgent issue that requires immediate merchant action. This example shows a fraud review alert with \[buttons]\(/docs/api/{API\_NAME}/{API\_VERSION}/web-components/actions/button) to review order details and adjust settings. ##### html ```html This order shows multiple risk indicators and cannot be auto-fulfilled. Review required within 24 hours to prevent automatic cancellation. Review order details Adjust fraud settings ``` * #### Confirm a completed action with a dismissible banner ##### Description Use a success-toned banner with the \`dismissible\` property to confirm a completed operation. This example shows a product import confirmation that merchants can dismiss once acknowledged. ##### html ```html Successfully imported 50 products to your store. ``` ## Best practices * **Focus on single actions:** Present one piece of information or required action per banner to maintain clarity and prevent confusion. * **Keep messages concise:** Write scannable content that merchants can quickly understand without spending time deciphering meaning or next steps. * **Provide clear actions:** Info, warning, and critical banners should include a call to action with specific next steps so merchants know how to proceed. * **Make dismissible when appropriate:** Allow merchants to dismiss banners unless immediate action's required. Avoid persistent banners that can't be closed. * **Position contextually:** Place banners outside sections for page-wide messages or inside sections for contextual messages relevant to specific content. ## Limitations * The dismissed state doesn't persist across page loads or sessions. You must implement your own persistence logic using local storage, cookies, or server-side state. * Multiple banners stack vertically without built-in prioritization or queueing. If you show multiple banners at once, all appear simultaneously. You must implement banner queueing logic yourself to show one at a time. * Banners can't be fixed or sticky at the top of the viewport. They scroll with page content. * Banners don't have built-in truncation or "read more" functionality. Very long banner messages will wrap to multiple lines, creating tall banners that dominate the screen.