The Shopify Polaris component library includes styled modules and components for merchant onboarding and account configuration within your sales channel, such as notice banners, setting controls, form inputs, and modals.
Your sales channel requires a screen if merchants need to take specific actions to interact with your platform. For example, merchants might need create content (posts, adds etc.), or listings for individual products. Use this empty state when merchants have successfully set up the sales channel and can publish content to your platform, but haven’t done so yet. The empty state has the following content guidelines:
Title: A concise explanation of why the merchant is seeing this screen.
Subtitle: A short sentence that communicates what the merchant has to do next.
Illustration: A visual to represent what the merchant needs to do.
Call to action (CTA): A button that directs the merchant to perform their primary task in this channel, such as “Add product” or “Create listing”.
Help footer: see Help footer section.
Basic page layout
Sales channels use the annotated layout component to build out the Contextual and Functional areas.
Contextual area (left of card, on desktop)
The title and description of each section is used to give the merchant context needed to make decisions in your sales channel.
Section heading: What information, feature, or functionality is the merchant dealing with in this section? Be concise, and use your own platform’s terminology where possible, such as “Inventory management”.
Description: A one-sentence description of why this information or functionality is important, and how it benefits the merchant. You can also include a text link pointing to documentation, or more information on your platform’s site, such as “[Learn more about feature name]”.
Functional area (card, main/right side, on desktop)
The main area of each section in a sales channel is used to give the merchant control of some part of their experience using your platform, or communicate vital information such as product publishing status, errors, or settings. Use the card component to build out this section.
The components below outline best practices for the functional area of a sales channel.
The account connection component sits at the top of the Account page and enables merchants to connect or disconnect their store to various accounts, such as your platform, or third party sites. The account connection componant also enables merchants to see which accounts are connected to Shopify through your channel and should always be visible, even if an account's status is disconnected.
Before an account is successfully connected, this section must link out to your channel/platform’s terms and conditions, and specify all charges or fees that a merchant incurs by using your channel. Clicking on the “Terms and conditions” link should open the terms hosted on your platform’s website in a new browser window.
The account connection component has the following design guidelines:
Section title: Name the platform or service you are asking the merchant to authenticate to, such as “Facebook account”, or “[your platform] account”.
Section description: Explain what the merchant benefit is for authenticating with the account. For example, “Connect your [sample] account to list your products” provides a clear statement of merchant value.
Connect button: Use consistent terminology, so that button actions match the requested merchant action (“Connect” etc.).
Clicking Connect should open your platform or service’s authorization page (OAuth) within a popup window. Within this window, merchants should clearly recognize your brand and be able to log in or sign up for your service. If your platform requires additional personal details such as billing, prompt merchants for that information within this popup.
Once successfully authorized, the popup should automatically close. Refresh the sales channel page to show the successful account connection.
If merchants must complete any additional setup steps or go through a review process, communicate this directly after successful account connection.
Otherwise, if there are no additional setup steps, your sales channel can display a success banner at the top of the page. The success banner appears once, and should not reappear if the merchant refreshes or returns to the page later.
Your sales channel can include settings or features that merchants can enable/disable, configure, or review. This can include settings for your platform that you choose to make available to merchants through your sales channel. Settings functionality includes the setting toggle, generic information, and customization options.
The setting toggle component is used to give the merchant control over specific features or options in your sales channel.
Be sure to include specific body content for both Enabled and Disabled states of the feature toggle.
Clearly state whether the feature is “enabled” or “disabled,” and then explain what the implications are to the merchant. For example,
“Automatic messages are disabled. Your customers will not receive automatic shipping updates.”
Unless it does not make sense for your specific use case, use “Enable” and “Disable” language consistently across your feature toggles, body content and buttons.
Sometimes features or options will be unavailable to merchants, and cannot be toggled. In this case, clearly state that the feature is “not available” and then provide a reason why. Also include, if possible, an actionable next step that merchants can take to make the functionality available.
Information areas are used to communicate static content to merchants using your sales channel. This could include any of the following: cost or fee structure, review status, account status, etc. Each information area has a title and a body area. Follow the same guidelines as the Contextual areas above for this content.
Customization options enable merchants to make complex configurations of your sales channel, and extend beyond the single feature scope of the setting toggle. Customization dropdown menus should have smart default settings that are clearly labeled and require titles, such as “Position” or “Color”.
The banners can be implemented with four different colors, each used for different purposes:
- Blue: Basic messages (Welcome messages, feature announcements, explaining next steps)
- Green: Success messages (channel setup, product publishing, successful content creation)
- Yellow: Low-impact status messages (store being reviewed, products being reviewed)
- Red: High-impact messages (Errors, products rejected/banned from the platform, store rejected/banned from the platform)
Banners have the following content guidelines:
Message: The main body of the banner. Maximum two sentences, unless the banner communicates multiple discrete elements, in which case a bullet list is used.
Call to action: Banner CTAs can be inline text links (lower priority) or buttons (higher priority). Use a button for directing merchants to resolve errors. Use inline links for additional links, such as helpful information, documentation, or pertinent sections of your channel or Shopify.
Bolding: Use bold text sparingly to set parts of the banner message apart for clarity. Bold things like product names or important information like waiting times.
Banners are usually shown at the top of the page. For highly contextual messaging, banners can be shown within sections. These banners typically refer to settings or features within that same section.
Forms use form areas to help user flow and lighten the burden on merchants. Refrain from using multi-step forms in your sales channel, and only ask for necessary information.
If your sales channel publishes products to a storefront, merchants will need to be notified of any relevant errors related to the products being displayed. The status box tells merchants how many of their products have been successfully published and the errors table lists all products that aren't displaying, as well as publication issues related to each product. This enables merchants to resolve issues and publish blocked products.
Within the Status card, show a count of products published to your sales channel. That count should link to Shopify's bulk editor, where merchants can easily see and manage published products.
The errors table should have no more than six products per page before paginating the table and displaying the page navigation controls.
Terms and conditions
Merchants using your sales channel should have access to your terms and conditions at all times. They should be hosted elsewhere, but linked to from the terms and conditions module. The module must be visible after account connection, located at the bottom of the Account page.
The help footer must exist on every page of your sales channel, and links to documentation or support for your sales channel.