Skip to contentShopify logoPolaris

Banner

Informs merchants about important changes or persistent conditions. Use this component if you need to communicate to merchants in a prominent way. Banners are placed at the top of the page or section they apply to, and below the page or section header.

Use to convey general information or actions that aren’t critical. For example, you might show a banner that asks for merchant feedback. Default banners contain lower priority information and should always be dismissible.

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

function BannerExample() {
  return (
    <Banner title="Order archived" onDismiss={() => {}}>
      <p>This order was archived on March 7, 2017 at 3:12pm EDT.</p>
    </Banner>
  );
}

Props

Want to help make this feature better? Please share your feedback.

interface BannerProps
title?string

Title content for the banner.

icon?any

Status icon to display in the banner. Use only major icons.

hideIcon?boolean

Renders the banner without a status icon.

status?'success' | 'info' | 'warning' | 'critical'

Sets the status of the banner.

children?React.ReactNode

The child elements to render in the banner.

action? &

Action for banner.

secondaryAction?

Action | Displays a secondary action.

onDismiss?() => void

Callback when banner is dismissed.

stopAnnouncements?boolean

Disables screen reader announcements when changing the content of the banner.

Best practices

Banners should:

  • Be used thoughtfully and sparingly for only the most important information.
  • Not be used to call attention to what a merchant needs to do in the UI instead of making the action clear in the UI itself.
  • Not be the primary entry point to information or actions merchants need on a regular basis.
  • Be dismissible unless they contain critical information or an important step merchants need to take.
  • Use the default icon for success, info, warning and critical statuses. If the status icon is changed, use only major icons.
  • Remove the status icon only in scenarios where it takes up too much space, such as very small breakpoints or in side navigation cards.

Placement

Banners should be placed in the appropriate context:

  • Banners relevant to an entire page should be placed at the top of that page, below the page header. They should occupy the full width of the content area.
  • Banners related to a section of a page (like a card, popover, or modal) should be placed inside that section, below any section heading. These banners have less spacing and a pared-back design to fit within a content context.
  • Banners related to an element more specific that a section should be placed immediately above or below that element.

Content guidelines

Banners should:

  • Focus on a single theme, piece of information, or required action to avoid overwhelming merchants.
  • Be concise and scannable—merchants shouldn’t need to spend a lot of time figuring out what they need to know and do.
  • Be limited to a few important calls to action with no more than one primary action.
  • Not be used for marketing information or upsell—use callout cards instead.

To learn about writing helpful and accessible error message text, see the guidelines for error messages.

Title

Banner titles should follow the content guidelines for headings and subheadings.

Body content

Body content should:

  • Be concise: keep content to 1 to 2 sentences where possible
  • Clarify the benefit of the main task
  • Be written in sentence case and use appropriate punctuation
  • Avoid repeating the heading
  • Explain how to resolve the issue, particularly for warning and critical banners

Do

Your online store has a maximum of 20 themes. Delete unused themes to add more.

Don’t

You have reached your theme limit. Your online store has reached its maximum of 20 themes. To add more themes, delete themes you’re no longer using.

Buttons and links should be:

  • Clear and predictable: merchants should be able to anticipate what will happen when they click a button. Never deceive merchants by mislabeling a button.

Do

Buy shipping label

Don’t

Buy

  • Action-led: buttons should always lead with a strong verb that encourages action. To provide enough context to merchants use the {verb}+{noun} format on buttons except in the case of common actions like Save, Close, Cancel, or OK.

Do

Activate Apple Pay

Don’t

Try Apple Pay

  • Scannable: avoid unnecessary words and articles such as the, an, or a.

Do

Add menu item

Don’t

Add a menu item

Link text should:

  • Set the expectation of where merchants will be taken

Do

Order #001

Don’t

Order

  • Use consistent content to label navigation. For example, if a navigational link leads to a page called Orders, label the link Orders.

Do

Payments

Don’t

Finance section

Secondary body content

Body content should be:

  • Actionable: start sentences with imperative verbs when telling merchants what actions are available to them (especially something new). Don’t use permissive language like “you can”.

Do

Get performance data for all your sales channels.

Don’t

Now you can get performance data for all your sales channels.

  • Structured for merchant success: always put the most critical information first.
  • Clear: use the verb “need” to help merchants understand when they’re required to do something.

Do

To buy a shipping label, you need to enter the total weight of your shipment, including packaging.

Don’t

To buy a shipping label, you must enter the total weight of your shipment, including packaging.

  • To inform merchants about a new feature or opportunity, use callout cards
  • To group similar concepts together in the interface, use a card

Accessibility

Banners provide context and assist workflows for merchants with disabilities.

  • Critical and warning banners have a role=”alert” and are announced by assistive technologies when they appear.
  • All other banners have a role=”status” and are read after any critical announcements.
  • All banners have an aria-live attribute and are announced by assistive technologies when their content is updated. These announcements can be disabled by using the prop stopAnnouncements.
  • Banners use aria-describedby to describe their purpose to assistive technologies when they’re announced or receive focus. If a banner has a title, then the title content is used for the aria-describedby. If the banner doesn’t have a title, then all of the banner content is used for the aria-describedby.
  • Banner containers have a tabindex=”0” and display a visible keyboard focus indicator. Because of this, merchants can discover banners while tabbing through forms or other interactions, and developers can programmatically move focus to banners.
  • Banners use a combination of icons and colors to show their meaning and level of importance to merchants.

Error notifications in forms

Critical banners

When merchants submit long or complex forms with errors, use a critical banner to summarize what went wrong. Place the banner at the top of the form and move focus to the banner when the form is submitted. This allows all merchants to move through the form in a logical order to correct the issues.

Inline errors

Always include inline error messages for specific form fields so that merchants know what to do in context as they correct their mistakes.

To learn about creating helpful and accessible error message text, see the guidelines for error messages.

Do

  • Put banners close in context to the problem they’re referring to
  • Give banners with a lot of information a clear title that summarizes their content
  • Move focus to banners if they’re relevant to the merchant’s current workflow and need to be addressed immediately

Don’t

  • Move focus to banners if they appear on page load, or outside the merchant’s current workflow
  • Use warning or critical (role=”alert”) banners to convey information that the merchant doesn’t need to address immediately