Migrate Banner from Polaris React

The Polaris banner component communicates important contextual feedback and next steps. It replaces the Polaris React Banner component from @shopify/polaris and is available as <s-banner>.

Keep field validation next to its field. Use s-banner when the message affects a section or the wider task.

import {useState} from 'react';

export function ShippingWeightBanner() {
  const [hidden, setHidden] = useState(false);

  return (
    <s-banner
      heading="127 products missing shipping weights"
      tone="warning"
      dismissible
      hidden={hidden}
      onDismiss={() => setHidden(true)}
    >
      Products without weights may show inaccurate shipping rates.
      <s-button
        slot="secondary-actions"
        variant="secondary"
        href="/products?filter=missing-weights"
      >
        Review products
      </s-button>
      <s-button
        slot="secondary-actions"
        variant="secondary"
        href="/settings/shipping"
      >
        Setup guide
      </s-button>
    </s-banner>
  );
}

import {Banner} from '@shopify/polaris';

interface ShippingWeightBannerProps {
  onDismiss(): void;
}

export function ShippingWeightBanner({
  onDismiss,
}: ShippingWeightBannerProps) {
  return (
    <Banner
      title="127 products missing shipping weights"
      tone="warning"
      onDismiss={onDismiss}
      action={{
        content: 'Review products',
        url: '/products?filter=missing-weights',
      }}
      secondaryAction={{
        content: 'Setup guide',
        url: '/settings/shipping',
      }}
    >
      Products without weights may show inaccurate shipping rates.
    </Banner>
  );
}

Anchor to Updated propertiesUpdated properties

The following properties are different in the Polaris banner component.

Anchor to titletitle

Rename title to heading. If the old banner intentionally had no title, omit heading; don't invent a heading only to fill the property.

Anchor to tonetone

The four Polaris React tone values remain available. The default has changed, so make the old default explicit when its informational meaning matters.

Choose the tone from the message's meaning rather than its preferred color. The new auto value is appropriate only when the banner doesn't communicate a specific success, warning, or critical state.

Anchor to childrenchildren

Move the banner's children into the default slot. Plain text can remain as text. Replace nested Polaris React components, such as lists or links, with their Polaris web component equivalents.

Anchor to action and secondaryActionaction and secondaryAction

Replace action descriptor objects with up to two s-button children in the secondary-actions slot. Use variant="secondary" or variant="auto".

Don't pass the old object through a compatibility wrapper. Rendering buttons as children makes their labels, navigation, loading state, and event handling independently testable.

Anchor to onDismissonDismiss

Replace onDismiss with the dismissible property and the dismiss event. In React, use onDismiss={handleDismiss}. The banner hides itself after dismissal; when React owns visibility, also set hidden to true in the handler so app state matches the rendered state.

Use afterhide instead when cleanup must wait until the hide transition finishes.

Anchor to Removed propertiesRemoved properties

Anchor to iconicon

s-banner doesn't accept a custom icon. It chooses an icon from tone. Remove imported Polaris React icon sources, and put any essential meaning from a custom icon into the heading or body text.

Anchor to hideIconhideIcon

s-banner doesn't support hiding its tone icon. Don't reproduce the banner with custom boxes only to remove the icon. If the content doesn't need banner semantics or visual prominence, migrate it to normal content in an s-section or s-box.

Anchor to stopAnnouncementsstopAnnouncements

s-banner doesn't expose an announcement override. If stopAnnouncements prevented frequently changing or non-urgent content from being announced, don't update that content inside a banner. Use normal page content, or update the banner only when there is a new message that merchants need to hear.

Anchor to New properties and eventsNew properties and events

Anchor to Test the migrationTest the migration

• Verify every banner tone still matches the message's meaning, especially banners that previously omitted tone.
• Test action navigation, click handlers, disabled state, and loading state.
• Dismiss the banner and confirm both the rendered banner and app-owned state remain hidden.
• Verify any persisted dismissal still survives the same reloads or sessions as before; s-banner doesn't persist it.
• Check the message with a screen reader, especially call sites that used stopAnnouncements.
• Remove unused Polaris React action objects, icon imports, and the Banner import after their final consumers are migrated.

Anchor to Related guidanceRelated guidance

• Banner component
• Banner best practices
• Migrate from Polaris React