banner

18 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Banner component purpose

Banners inform merchants about important changes or persistent conditions in a prominent way. They are placed at the top of the page or section they apply to, and below the page or section header.

Banner tones and variants

Banners support the following tones: default (for general information or lower priority), informational (to update merchants about changes or give advice), success (for delayed, persistent, or action-backed feedback), warning (for information needing attention or merchant action), and critical (for problems requiring immediate resolution).

Banner dismissibility rule

Banners should be dismissible unless they contain critical information or an important action that merchants are required to take.

Banner icon guidance

Banners should use the default icon for success, info, warning, and critical tones. If the status icon is changed, use only major icons (20x20). Remove the status icon only in scenarios where it takes up too much space, such as very small breakpoints or in side navigation cards.

Banner placement contexts

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

Banner content best practices

Banners should focus on a single theme, piece of information, or required action to avoid overwhelming merchants. Content should be concise and scannable—merchants shouldn't need to spend much time figuring out what they need to know and do. Banners should be limited to a few important calls to action with no more than one primary action. Banners should not be used for marketing information or upsell.

Banner body content guidelines

Body content should be concise with 1 to 2 sentences where possible. It should clarify the benefit of the main task, be written in sentence case with appropriate punctuation, avoid repeating the heading, and explain how to resolve the issue, particularly for warning and critical banners. Example: 'Your online store has a maximum of 20 themes. Delete unused themes to add more.' Avoid: '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.'

Banner button and link guidance

Buttons and links should be clear and predictable—merchants should be able to anticipate what will happen when they click. Buttons should be action-led with a strong verb that encourages action, using the {verb}+{noun} format except for common actions like Save, Close, Cancel, or OK. Button text should be scannable and avoid unnecessary words and articles like 'the', 'an', or 'a'. Example button: 'Activate Apple Pay' (not 'Try Apple Pay'). Example link: 'Order #001' (not 'Order'). Links should use consistent content to label navigation, such as 'Payments' rather than 'Finance section'.

Banner secondary body content rules

Secondary body content should be actionable—start sentences with imperative verbs when telling merchants what actions are available. Use 'you need to' rather than permissive language like 'you can'. Put the most critical information first. Example: 'Get performance data for all your sales channels.' (not 'Now you can get performance data for all your sales channels.'). Use the verb 'need' to help merchants understand when they're required to do something. Example: 'To buy a shipping label, you need to enter the total weight of your shipment, including packaging.' (not 'you must').

Banner accessibility roles

Critical and warning banners have role='alert' and are announced by assistive technologies when they appear. All other banners have 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. Announcements can be disabled using the prop stopAnnouncements.

Banner aria-describedby implementation

Banners use aria-describedby to describe their purpose to assistive technologies when announced or receiving focus. If a banner has a title, the title content is used for aria-describedby. If the banner doesn't have a title, all of the banner content is used for aria-describedby.

Banner keyboard focus and tabindex

Banner containers have tabindex='0' and display a visible keyboard focus indicator. Merchants can discover banners while tabbing through forms or other interactions, and developers can programmatically move focus to banners.

Banner meaning conveyed through icons and colors

Banners use a combination of icons and colors to show their meaning and level of importance to merchants.

Critical banners in form error handling

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 merchants to move through the form in a logical order to correct issues. Always include inline error messages for specific form fields so merchants know what to do in context as they correct mistakes.

Banner focus movement accessibility rules

Move focus to banners if they are relevant to the merchant's current workflow and need to be addressed immediately. Do not move focus to banners if they appear on page load or outside the merchant's current workflow. Do not use warning or critical (role='alert') banners to convey information that the merchant doesn't need to address immediately. 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.

Banner general best practices

Banners should be used thoughtfully and sparingly for only the most important information. They should 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. Banners should not be the primary entry point to information or actions merchants need on a regular basis.

Banner web component

The Banner component is available as a web component named 's-banner' at https://shopify.dev/docs/api/app-home/polaris-web-components/feedback/banner of type polaris.

Banner status prop replaced with tone

In v12, the Banner component's status prop is replaced with tone. The migration changes <Banner status="success" /> to <Banner tone="success" />.

Give your agent this brain