PolarisComponents
Actions
Account connection
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.
Button
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
Button group displays multiple related actions stacked or in a horizontal row to help with arrangement and spacing.
Page actions
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
Bleed
AlphaApplies negative margin to allow content to bleed out into the surrounding layout.
Box
AlphaBox is the most primitive layout component. It’s a way to access Polaris design tokens.
Callout card
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.
Card
AlphaCards 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.
Divider
AlphaUse to separate or group content.
Empty state
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.
Form layout
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.
Grid
AlphaCreate complex layouts based on CSS Grid.
Horizontal grid
AlphaUse to lay out children horizontally with equal gap between columns. Based on CSS Grid.
Horizontal stack
AlphaUse to display children horizontally in a row. Based on CSS Flexbox.
Layout
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.
Legacy card
LegacyThis 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.
Legacy stack
LegacyThis 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 card
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.
Page
Use to build the outer wrapper of a page, including the page title and associated actions.
Vertical stack
AlphaUse to display children vertically and horizontally with full width by default. Based on CSS Flexbox.
Selection and input
Legacy filters
DeprecatedThis is a legacy version of the Filters component, which is a composite component that filters the items of a list or table.
Autocomplete
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.
Checkbox
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.
Choice list
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.
Color picker
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
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 picker
Date pickers let merchants choose dates from a visual calendar that’s consistently applied wherever dates need to be selected across Shopify.
Drop zone
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
Filters is a composite component that filters the items of a list or table.
Form
A wrapper component that handles the submission of forms.
Index filters
Use index filters to allow merchants to filter, search, and sort their index table data and create unique saved views from the results.
Inline error
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.
Radio button
Use radio buttons to present each item in a list of options where merchants must make a single selection.
Range slider
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
Select lets merchants choose one option from an options menu. Consider select when you have 4 or more options, to avoid cluttering the interface.
Tag
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.
Text field
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
Avatar
Avatars are used to show a thumbnail representation of an individual or business in the interface.
Icon
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
Keyboard key is used to educate merchants about keyboard shortcuts.
Thumbnail
Use thumbnails as a visual anchor and identifier for an object. They should be used along with text to provide context.
Video thumbnail
Video thumbnails are a clickable placeholder image. When clicked, it opens a video player within a modal or full screen.
Feedback indicators
Badge
Badges are used to inform merchants of the status of an object or of an action that’s been taken.
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.
Exception list
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.
Loading
The loading component is used to indicate to merchants that a page is loading or an upload is processing.
Progress bar
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
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
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
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.
Spinner
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.
Toast
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.
Tables
Data table
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.
Index table
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.
Lists
Action list
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 list
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.
List
Lists display a set of related text-only content. Each list item begins with a bullet or a number.
Listbox
A Listbox is a vertical list of interactive options, with room for icons, descriptions, and other elements.
Option list
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 item
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.
Resource list
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.
Navigation
Footer help
Footer help is used to refer merchants to more information related to the product or feature they’re using.
Fullscreen bar
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`.
Legacy tabs
LegacyUse to alternate among related views within the same context.
Link
Links take users to another place, and usually appear within or directly following a sentence.
Navigation
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.
Pagination
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.
Tabs
Use to alternate among related views within the same context.
Top bar
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.
Overlays
Modal
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.
Popover
Popovers are small overlays that open on demand. They let merchants access additional content and actions without cluttering the page.
Tooltip
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.
Utilities
App provider
App provider is a required component that enables sharing global settings throughout the hierarchy of your application.
Collapsible
The collapsible component is used to put long sections of information under a block that merchants can expand or collapse.
Frame
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.
Scrollable
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.
Deprecated
Caption
DeprecatedCaption 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 text
DeprecatedDisplay 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.
Heading
DeprecatedHeadings 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.
Setting toggle
DeprecatedUse to give merchants control over a feature or option that can be turned on or off.
Sheet
DeprecatedA 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.
Subheading
DeprecatedSubheadings are used for the title of any sub-sections in top-level page sections.
Text container
DeprecatedA text container is used to wrap text elements such as paragraphs, headings, and lists to give them vertical spacing.
Text style
DeprecatedText style enhances text with additional visual meaning. For example, using subdued text to de-emphasize it from its surrounding text.
Visually hidden
DeprecatedUse when an element needs to be available to assistive technology (for example, a screen reader) but otherwise hidden.