---
title: Migrate to the Polaris banner component
description: >-
  Learn how to migrate the Banner component to Polaris web components in
  checkout and customer account UI extensions.
source_url:
  html: >-
    https://shopify.dev/docs/apps/build/checkout/migrate-to-web-components/banner
  md: >-
    https://shopify.dev/docs/apps/build/checkout/migrate-to-web-components/banner.md
---

# Migrate to the Polaris banner component

The Polaris banner component highlights important status messages, warnings, or required actions so customers can resolve issues or stay informed. It replaces the previous [`Banner`](https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/ui-components/feedback-and-status-indicators/banner) component and is available as [`<s-banner>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/feedback-and-status-indicators/banner) in API versions 2025-10 and newer.

***

## Updated properties

The following properties are different in the Polaris banner component.

### title

The previous `Banner` `title` prop is now called [`heading`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/feedback-and-status-indicators/banner#properties-propertydetail-heading).

### status

The previous `Banner` `status` prop is now called [`tone`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/feedback-and-status-indicators/banner#properties-propertydetail-tone). The default changed from `'info'` to `'auto'`.

### on​Dismiss

In the previous component, providing `onDismiss` automatically made the banner dismissible. Now you must also set [`dismissible`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/feedback-and-status-indicators/banner#properties-propertydetail-dismissible) to `true`.

## Migrating onDismiss

##### Latest (Preact)

```tsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';
import {useState} from 'preact/hooks';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  const [visible, setVisible] = useState(true);

  if (!visible) return null;

  return (
    <s-banner
      heading="Payment processed"
      tone="success"
      dismissible
      onDismiss={() => setVisible(false)}
    >
      Your order has been confirmed.
    </s-banner>
  );
}
```

##### Pre-Polaris (2025-07)

```tsx
import {useState} from 'react';
import {
  reactExtension,
  Banner,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  const [visible, setVisible] = useState(true);

  if (!visible) return null;

  return (
    <Banner
      title="Payment processed"
      status="success"
      onDismiss={() => setVisible(false)}
    >
      Your order has been confirmed.
    </Banner>
  );
}
```

***

## New properties

The Polaris banner component introduces the following new properties:

| New prop | Type | Description |
| - | - | - |
| [`dismissible`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/feedback-and-status-indicators/banner#properties-propertydetail-dismissible) | `boolean` | Controls whether the banner can be dismissed. Must be `true` when using `onDismiss`. |
| [`hidden`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/feedback-and-status-indicators/banner#properties-propertydetail-hidden) | `boolean` | Controls the visibility of the banner. |
| [`onAfterHide`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/feedback-and-status-indicators/banner#events-propertydetail-afterhide) | `function` | Fires after the banner has fully hidden. |

***