The account connection component is used so merchants can connect or disconnect their store to various accounts. For example, if merchants want to use the Facebook sales channel, they need to connect their Facebook account to their Shopify store.
Buttons are used primarily for actions, such as “Add”, “Close”, “Cancel”, or “Save”. Plain buttons, which look similar to links, are used for less important or less commonly used actions, such as “view shipping settings”.
Button group displays multiple related actions stacked or in a horizontal row to help with arrangement and spacing.
Page actions let merchants take key actions at the bottom of specific pages in the interface. This is important because sometimes the primary call to action is hard to access when merchants are at the bottom of a page.
Layout and structure
Applies negative margin to allow content to bleed out into the surrounding layout.
Box is the most primitive layout component. It’s a way to access Polaris design tokens.
Callout cards are used to encourage merchants to take an action related to a new feature or opportunity. They are most commonly displayed in the sales channels section of Shopify.
Cards are used to group similar concepts and tasks together for merchants to scan, read, and get things done. It displays content in a familiar and recognizable style.
Use to separate or group content.
Empty states are used when a list, table, or chart has no items or data to show. This is an opportunity to provide explanation or guidance to help merchants progress. The empty state component is intended for use when a full page in the admin is empty, and not for individual elements or areas in the interface.
Use form layout to arrange fields within a form using standard spacing. By default it stacks fields vertically but also supports horizontal groups of fields.
Create complex layouts based on CSS Grid.
Use to lay out children horizontally with equal gap between columns. Based on CSS Grid.
Use to display children horizontally in a row. Based on CSS Flexbox.
The layout component is used to create the main layout on a page. Layouts sections come in three main configurations. one-column, two-column, and annotated. One and two column layouts can be combined in the same page. Annotated layouts should be used on their own and only on settings pages.
This is the legacy version of the Card component which is in the process of being updated to a more flexible and composable API. Cards are used to group similar concepts and tasks together to make Shopify easier for merchants to scan, read, and get things done.
This is the legacy version of the Stack component which is in the process of being updated to a more flexible and composable API. Use to lay out a horizontal row of components or to achieve no-fuss vertical centering. A stack is made of flexible items that wrap each of the stack’s children. Options provide control of the wrapping, spacing, and relative size of the items in the stack.
Media cards provide a consistent layout to present visual information to merchants. Visual media is used to provide additional context to the written information it's paired with.
Use to build the outer wrapper of a page, including the page title and associated actions.
Use to display children vertically and horizontally with full width by default. Based on CSS Flexbox.
Selection and input
This is a legacy version of the Filters component, which is a composite component that filters the items of a list or table.
The autocomplete component is an input field that provides selectable suggestions as a merchant types into it. It allows merchants to quickly search through and select from large collections of options. It's a convenience wrapper around the `Combobox` and `Listbox` components with minor UI differences.
Checkboxes are most commonly used to give merchants a way to make a range of selections (zero, one, or multiple). They may also be used as a way to have merchants indicate they agree to specific terms and services.
A choice list lets you create a list of grouped radio buttons or checkboxes. Use this component if you need to group together a related list of interactive choices.
The color picker is used to let merchants select a color visually. For example, merchants use the color picker to customize the accent color of the email templates for their shop.
Combobox is an accessible autocomplete input that enables merchants to filter a list of options and select one or more values.
Contextual save bar
The contextual save bar tells merchants their options once they have made changes to a form on the page. This component is also shown while creating a new object like a product or customer. Merchants can use this component to save or discard their work.
Date pickers let merchants choose dates from a visual calendar that’s consistently applied wherever dates need to be selected across Shopify.
The drop zone component lets users upload files by dragging and dropping the files into an area on a page, or activating a button.
Filters is a composite component that filters the items of a list or table.
A wrapper component that handles the submission of forms.
Use index filters to allow merchants to filter, search, and sort their index table data and create unique saved views from the results.
Inline errors are brief, in-context messages that tell merchants something went wrong with a single or group of inputs in a form. Use inline errors to help merchants understand why a form input may not be valid and how to fix it.
Use radio buttons to present each item in a list of options where merchants must make a single selection.
A range slider is an input field that merchants can use to select a numeric value within a given range (minimum and maximum values).
Select lets merchants choose one option from an options menu. Consider select when you have 4 or more options, to avoid cluttering the interface.
Tags represent a set of interactive, merchant-supplied keywords that help label, organize, and categorize objects. Tags can be added or removed from an object by merchants.
A text field is an input field that merchants can type into. It has a range of options and supports several text formats including numbers.
Images and icons
Avatars are used to show a thumbnail representation of an individual or business in the interface.
Icons are used to visually communicate core parts of the product and available actions. They can act as wayfinding tools to help merchants more easily understand where they are in the product, and common interaction patterns that are available.
Keyboard key is used to educate merchants about keyboard shortcuts.
Use thumbnails as a visual anchor and identifier for an object. They should be used along with text to provide context.
Video thumbnails are a clickable placeholder image. When clicked, it opens a video player within a modal or full screen.
Badges are used to inform merchants of the status of an object or of an action that’s been taken.
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 exception lists to help merchants notice important, standout information that adds extra context to a task. Exception lists often consist of a title and description. Each item in the list either has a bullet or icon at the front.
The loading component is used to indicate to merchants that a page is loading or an upload is processing.
The progress bar component is used to visually represent the completion of a task or operation. It shows how much of the task has been completed and how much is still left.
Skeleton body text
Skeleton body text is used to provide a low fidelity representation of content before it appears on the page, and improves load times perceived by merchants. Can be used for content in or outside of a card.
Skeleton display text
Skeleton display text is used to provide a low fidelity representation of content before it appears on the page, and improves load times perceived by merchants. Can be used for content in or outside of a card.
Skeleton page is used with other skeleton loading components to provide a low fidelity representation of the user interface (UI) before content appears on the page. It improves load times perceived by merchants.
Skeleton tabs are used to provide a low fidelity representation of content before it appears on the page, and improves load times perceived by merchants. Can be used for content in or outside of a card.
Skeleton thumbnail is used to provide a low fidelity representation of an image before it appears on the page, and improves load times perceived by merchants. Use for thumbnails in or outside of a card.
Spinners are used to notify merchants that their action is being processed. For loading states, spinners should only be used for content that can’t be represented with skeleton loading components, like for data charts.
The toast component is a non-disruptive message that appears at the bottom of the interface to provide quick, at-a-glance feedback on the outcome of an action.
Data tables are used to organize and display all information from a data set. While a data visualization represents part of data set, a data table lets merchants view details from the entire set. This helps merchants compare and analyze the data.
An index table displays a collection of objects of the same type, like orders or products. The main job of an index table is to help merchants get an at-a-glance of the objects to perform actions or navigate to a full-page representation of it.
Action lists render a list of actions or selectable options. This component is usually placed inside a popover container to create a dropdown menu or to let merchants select from a list of options.
Description lists are a way to organize and explain related information. They’re particularly useful when you need to list and define terms such as in a glossary.
Lists display a set of related text-only content. Each list item begins with a bullet or a number.
A Listbox is a vertical list of interactive options, with room for icons, descriptions, and other elements.
The option list component lets you create a list of grouped items that merchants can pick from. This can include single selection or multiple selection of options. Option list usually appears in a popover, and sometimes in a modal or a sidebar. Option lists are styled differently than choice lists and should not be used within a form, but as a standalone menu.
Resource items represent specific objects within a collection, such as products or orders. They provide contextual information on the resource type and link to the object’s detail page.
A resource list displays a collection of objects of the same type, like products or customers. The main job of a resource list is to help merchants find an object and navigate to a full-page representation of it.
Footer help is used to refer merchants to more information related to the product or feature they’re using.
The Fullscreen bar is a header component that should be presented at the top of an app when it is in fullscreen mode. This is designed to ensure a uniform placement for a button to exit that mode. The Fullscreen bar can be customized by adding `children`.
Use to alternate among related views within the same context.
Links take users to another place, and usually appear within or directly following a sentence.
The navigation component is used to display the primary navigation in the sidebar of the frame of an application. Navigation includes a list of links that merchants use to move between sections of the application.
Use pagination to let merchants move through an ordered collection of items that has been split into pages. On the web, pagination uses buttons to move back and forth between pages. On iOS and Android, pagination uses infinite scrolling.
Use to alternate among related views within the same context.
The top bar is a header component that allows merchants to search, access menus, and navigate by clicking on the logo. It’s always visible at the top of interfaces like Shopify or Shopify Plus. Third-party apps that use the top bar can customize the color to match their brand using the app provider component and are required to use their own logo.
Modals are overlays that require merchants to take an action before they can continue interacting with the rest of Shopify. They can be disruptive and should be used thoughtfully and sparingly.
Popovers are small overlays that open on demand. They let merchants access additional content and actions without cluttering the page.
Tooltips are floating labels that briefly explain the function of a user interface element. They can be triggered when merchants hover, focus, tap, or click.
App provider is a required component that enables sharing global settings throughout the hierarchy of your application.
The collapsible component is used to put long sections of information under a block that merchants can expand or collapse.
The frame component, while not visible in the user interface itself, provides the structure for an application. It wraps the main elements and houses the primary navigation, top bar, toast, and contextual save bar components.
The scrollable component is a container for long form content, such as terms of service, that allows for scrolling so merchants can expose more text as they read.
Caption text size is smaller than the recommended size for general reading. On web, it should be used only in a graph or as a timestamp for a list item. On Android and iOS, it can also be used as help text or as other kinds of secondary text for list items.
Display styles make a bold visual statement. Use them to create impact when the main goal is visual storytelling. For example, use display text to convince or reassure merchants such as in marketing content or to capture attention during onboarding.
Headings are used as the titles of each major section of a page in the interface. For example, card components generally use headings as their title.
Use to give merchants control over a feature or option that can be turned on or off.
A sheet is a large container that enters from the edge of the screen when triggered by the merchant. It’s used to provide merchants with actions and information contextual to the page. It doesn’t interrupt their flow like a modal.
Subheadings are used for the title of any sub-sections in top-level page sections.
A text container is used to wrap text elements such as paragraphs, headings, and lists to give them vertical spacing.
Text style enhances text with additional visual meaning. For example, using subdued text to de-emphasize it from its surrounding text.
Use when an element needs to be available to assistive technology (for example, a screen reader) but otherwise hidden.