Skip to main content
Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

Banner

Use banners to communicate important messages to customers in a prominent way. Banners support multiple status tones to convey urgency, and can be made dismissible or collapsible depending on the context.

For inline status indicators on individual items, use Badge instead.

Support
Targets (25)

Supported targets

Anchor to PropertiesProperties

Configure the following properties on the Banner component.

Anchor to collapsible
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.

Anchor to id
id
string

A unique identifier for the component. Use this to target the component in scripts or stylesheets, or to distinguish it from other instances of the same component.

Anchor to onDismiss
onDismiss
() => void

A callback that fires when the banner is dismissed by the user. This component is controlled, so you must manage the visibility of the banner in state by using the onDismiss callback.

Anchor to status
status
Default: 'info'

The semantic meaning and color treatment of the banner.

Anchor to title
title
string

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

Anchor to ExamplesExamples

Anchor to Display a critical errorDisplay a critical error

Use a critical banner to communicate problems that require immediate customer action. This example shows a payment verification error with a concise, actionable message.

Display a critical error

A critical banner displaying a payment verification error.

Display a critical error

import {
reactExtension,
Banner,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
'customer-account.page.render',
() => <Extension />,
);

function Extension() {
return (
<Banner
status="critical"
title="Your payment details couldn’t be verified. Check your card details and try again."
/>
);
}
import {extension, Banner} from '@shopify/ui-extensions/customer-account';

export default extension('customer-account.page.render', (root) => {
const banner = root.createComponent(Banner, {
status: 'critical',
title:
'Your payment details couldn’t be verified. Check your card details and try again.',
});

root.appendChild(banner);
});

Anchor to Show a dismissible info bannerShow a dismissible info banner

Let customers dismiss informational banners after reading them. This example uses onDismiss to remove the banner when the close button is pressed. The Banner component is controlled, so you must manage visibility in state.

Show a dismissible info banner

import {useState} from 'react';
import {
reactExtension,
Banner,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
'customer-account.page.render',
() => <Extension />,
);

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

if (!visible) {
return null;
}

return (
<Banner
status="info"
title="Your next subscription order ships on March 15."
onDismiss={() => setVisible(false)}
/>
);
}
import {extension, Banner} from '@shopify/ui-extensions/customer-account';

export default extension('customer-account.page.render', (root) => {
const banner = root.createComponent(Banner, {
status: 'info',
title: 'Your next subscription order ships on March 15.',
onDismiss: () => {
root.removeChild(banner);
},
});

root.appendChild(banner);
});

Anchor to Present a collapsible warningPresent a collapsible warning

Use a collapsible banner to show a warning title with additional details hidden by default. This example warns about an expiring payment method and reveals instructions when expanded.

Present a collapsible warning

import {
reactExtension,
Banner,
Text,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
'customer-account.page.render',
() => <Extension />,
);

function Extension() {
return (
<Banner
status="warning"
title="Your subscription payment method expires soon"
collapsible
>
<Text>
Update your payment method before April 1 to
avoid interruption to your subscription.
</Text>
</Banner>
);
}
import {
extension,
Banner,
Text,
} from '@shopify/ui-extensions/customer-account';

export default extension('customer-account.page.render', (root) => {
const banner = root.createComponent(
Banner,
{
status: 'warning',
title: 'Your subscription payment method expires soon',
collapsible: true,
},
[
root.createComponent(
Text,
undefined,
'Update your payment method before April 1 to avoid interruption to your subscription.',
),
],
);

root.appendChild(banner);
});

Anchor to Best practicesBest practices

  • Use banners sparingly: Too many banners distract customers from the main content. 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 component with a clear action so customers know what to do after reading the message.
  • Make banners dismissible unless critical: Customers should be able to dismiss informational banners. Keep critical banners persistent until the issue is resolved.
  • Match status to urgency: Use info for general updates, warning for issues needing attention, success for confirmations, and critical for problems that block progress.

Anchor to LimitationsLimitations

  • The Banner component is controlled. You must manage banner visibility in state using the onDismiss callback.
  • Collapsible banners conceal child elements by default. The title is always visible.
  • Banners don't have a built-in auto-dismiss timer. You must implement timed dismissal manually if needed.
Was this page helpful?