SBanner <s-banner>

A prominent message that surfaces important information, warnings or errors at the top of a page or section. SBanner is the typed Vue 3 wrapper for Shopify's Polaris <s-banner> web component.

import { SBanner } from 'polaris-vue-elements'

Best practices

• Cover one thing per banner. Each banner should carry a single message or a single required action, so merchants aren't left wondering what it's about.
• Write for a quick scan. Keep the text short enough that merchants grasp the message and what to do next at a glance.
• Give merchants a next step. Banners with tone="info", tone="warning" or tone="critical" should include a call to action that says specifically how to proceed.
• Let merchants close banners. Set dismissible unless the message needs immediate action, and avoid banners that stay on screen with no way to close them.
• Place banners by scope. Put a banner outside any section for a message about the whole page, or inside a section when it concerns that section's content.

<SBanner heading="Shipping rates need updating" tone="warning" dismissible>
  Some of your shipping zones have no rates, so customers there can't check out.
  <template #secondary-actions>
    <SButton variant="secondary">Review shipping zones</SButton>
  </template>
</SBanner>

See Shopify's best practices for <s-banner> for the full guidance.

Example

Your changes have been saved.We couldn't process the payment. Please try again.Retry

<script setup>
import { ref } from 'vue'
import { SBanner, SButton, SText } from 'polaris-vue-elements'

const showCritical = ref(true)
</script>

<template>
  <!-- SBanner needs default-slot content — a `heading` alone renders an empty
       banner. See docs/guide/quirks.md. -->
  <SBanner heading="Order updated" tone="success">
    <SText>Your changes have been saved.</SText>
  </SBanner>

  <!-- dismissible banners fire `dismiss` immediately, then `afterhide` once any
       animation completes; drive `hidden` (or v-if, as here) from that event. -->
  <SBanner
    v-if="showCritical"
    heading="Something went wrong"
    tone="critical"
    dismissible
    @dismiss="showCritical = false"
  >
    <SText>We couldn't process the payment. Please try again.</SText>
    <template #secondary-actions>
      <SButton variant="secondary">Retry</SButton>
    </template>
  </SBanner>
</template>

Props

Prop	Type	Description
dismissible	boolean	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	The heading text displayed at the top of the banner.
hidden	boolean	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	"auto" | "info" | "success" | "warning" | "critical"	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

Event	Type
afterhide	CustomEvent
dismiss	CustomEvent

Listen for these with @afterhide-style listeners on <SBanner>.

Slots

Slot	Description
default	The main message content displayed within the banner component, providing important information or guidance to users.
secondary-actions	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".