# Table of Contents
- [Foundations — Shopify Polaris React](#foundations-shopify-polaris-react)
- [Shopify Polaris React](#shopify-polaris-react)
- [Getting Started — Shopify Polaris React](#getting-started-shopify-polaris-react)
- [Content — Shopify Polaris React](#content-shopify-polaris-react)
- [Polaris 101 — Shopify Polaris React](#polaris-101-shopify-polaris-react)
- [Accessibility — Shopify Polaris React](#accessibility-shopify-polaris-react)
- [Design — Shopify Polaris React](#design-shopify-polaris-react)
- [Patterns — Shopify Polaris React](#patterns-shopify-polaris-react)
- [Components — Shopify Polaris React](#components-shopify-polaris-react)
- [Component lifecycle — Shopify Polaris React](#component-lifecycle-shopify-polaris-react)
- [Formatting localized currency — Shopify Polaris React](#formatting-localized-currency-shopify-polaris-react)
- [Building with Polaris — Shopify Polaris React](#building-with-polaris-shopify-polaris-react)
- [Listbox — Shopify Polaris React](#listbox-shopify-polaris-react)
- [Action list — Shopify Polaris React](#action-list-shopify-polaris-react)
- [List — Shopify Polaris React](#list-shopify-polaris-react)
- [Resource item — Shopify Polaris React](#resource-item-shopify-polaris-react)
- [Description list — Shopify Polaris React](#description-list-shopify-polaris-react)
- [Option list — Shopify Polaris React](#option-list-shopify-polaris-react)
- [Resource list — Shopify Polaris React](#resource-list-shopify-polaris-react)
- [Footer help — Shopify Polaris React](#footer-help-shopify-polaris-react)
- [Link — Shopify Polaris React](#link-shopify-polaris-react)
- [Pagination — Shopify Polaris React](#pagination-shopify-polaris-react)
- [Tabs — Shopify Polaris React](#tabs-shopify-polaris-react)
- [Overlays — Shopify Polaris React](#overlays-shopify-polaris-react)
- [Popover — Shopify Polaris React](#popover-shopify-polaris-react)
- [Tooltip — Shopify Polaris React](#tooltip-shopify-polaris-react)
- [Utilities — Shopify Polaris React](#utilities-shopify-polaris-react)
- [App provider — Shopify Polaris React](#app-provider-shopify-polaris-react)
- [Collapsible — Shopify Polaris React](#collapsible-shopify-polaris-react)
- [Scrollable — Shopify Polaris React](#scrollable-shopify-polaris-react)
- [Deprecated — Shopify Polaris React](#deprecated-shopify-polaris-react)
- [Caption — Shopify Polaris React](#caption-shopify-polaris-react)
- [Contextual save bar — Shopify Polaris React](#contextual-save-bar-shopify-polaris-react)
- [Display text — Shopify Polaris React](#display-text-shopify-polaris-react)
- [Frame — Shopify Polaris React](#frame-shopify-polaris-react)
- [Unknown](#unknown)
- [Version 11 Layout — Shopify Polaris React](#version-11-layout-shopify-polaris-react)
- [Documenting in Polaris — Shopify Polaris React](#documenting-in-polaris-shopify-polaris-react)
- [Version 11 Color — Shopify Polaris React](#version-11-color-shopify-polaris-react)
- [Contributing to Polaris React — Shopify Polaris React](#contributing-to-polaris-react-shopify-polaris-react)
- [Contributing to the Figma UI Kit — Shopify Polaris React](#contributing-to-the-figma-ui-kit-shopify-polaris-react)
- [Version 10 Typography — Shopify Polaris React](#version-10-typography-shopify-polaris-react)
- [Density — Shopify Polaris React](#density-shopify-polaris-react)
- [Contributing to Polaris Icons — Shopify Polaris React](#contributing-to-polaris-icons-shopify-polaris-react)
- [Version 11 Tokens — Shopify Polaris React](#version-11-tokens-shopify-polaris-react)
- [Stylelint Polaris — Shopify Polaris React](#stylelint-polaris-shopify-polaris-react)
- [Version 12 — Shopify Polaris React](#version-12-shopify-polaris-react)
- [Spacial organization — Shopify Polaris React](#spacial-organization-shopify-polaris-react)
- [Fullscreen bar — Shopify Polaris React](#fullscreen-bar-shopify-polaris-react)
- [Polaris Migrator — Shopify Polaris React](#polaris-migrator-shopify-polaris-react)
- [Font — Shopify Polaris React](#font-shopify-polaris-react)
- [Heading — Shopify Polaris React](#heading-shopify-polaris-react)
- [Migrating from v11 to v12 — Shopify Polaris React](#migrating-from-v11-to-v12-shopify-polaris-react)
- [Legacy card — Shopify Polaris React](#legacy-card-shopify-polaris-react)
- [Legacy filters — Shopify Polaris React](#legacy-filters-shopify-polaris-react)
- [Legacy stack — Shopify Polaris React](#legacy-stack-shopify-polaris-react)
- [Legacy tabs — Shopify Polaris React](#legacy-tabs-shopify-polaris-react)
- [Loading — Shopify Polaris React](#loading-shopify-polaris-react)
- [Page actions — Shopify Polaris React](#page-actions-shopify-polaris-react)
- [Modal — Shopify Polaris React](#modal-shopify-polaris-react)
- [Subheading — Shopify Polaris React](#subheading-shopify-polaris-react)
- [Sheet — Shopify Polaris React](#sheet-shopify-polaris-react)
- [Text style — Shopify Polaris React](#text-style-shopify-polaris-react)
- [Text container — Shopify Polaris React](#text-container-shopify-polaris-react)
- [Toast — Shopify Polaris React](#toast-shopify-polaris-react)
- [Visually hidden — Shopify Polaris React](#visually-hidden-shopify-polaris-react)
- [Navigation — Shopify Polaris React](#navigation-shopify-polaris-react)
- [Top bar — Shopify Polaris React](#top-bar-shopify-polaris-react)
- [Setting toggle — Shopify Polaris React](#setting-toggle-shopify-polaris-react)
- [Icons — Shopify Polaris React](#icons-shopify-polaris-react)
- [Border — Shopify Polaris React](#border-shopify-polaris-react)
- [Shadow — Shopify Polaris React](#shadow-shopify-polaris-react)
- [Breakpoints — Shopify Polaris React](#breakpoints-shopify-polaris-react)
- [Space — Shopify Polaris React](#space-shopify-polaris-react)
- [Height — Shopify Polaris React](#height-shopify-polaris-react)
- [Text — Shopify Polaris React](#text-shopify-polaris-react)
- [Width — Shopify Polaris React](#width-shopify-polaris-react)
- [Motion — Shopify Polaris React](#motion-shopify-polaris-react)
- [Z-Index — Shopify Polaris React](#z-index-shopify-polaris-react)
- [Shopify Polaris React](#shopify-polaris-react)
- [border/at-rule-disallowed-list — Shopify Polaris React](#border-at-rule-disallowed-list-shopify-polaris-react)
- [border/custom-property-disallowed-list — Shopify Polaris React](#border-custom-property-disallowed-list-shopify-polaris-react)
- [border/declaration-property-unit-disallowed-list — Shopify Polaris React](#border-declaration-property-unit-disallowed-list-shopify-polaris-react)
- [color/at-rule-disallowed-list — Shopify Polaris React](#color-at-rule-disallowed-list-shopify-polaris-react)
- [border/function-disallowed-list — Shopify Polaris React](#border-function-disallowed-list-shopify-polaris-react)
- [color/color-named — Shopify Polaris React](#color-color-named-shopify-polaris-react)
- [color/function-disallowed-list — Shopify Polaris React](#color-function-disallowed-list-shopify-polaris-react)
- [color/global-disallowed-list — Shopify Polaris React](#color-global-disallowed-list-shopify-polaris-react)
- [color/custom-property-disallowed-list — Shopify Polaris React](#color-custom-property-disallowed-list-shopify-polaris-react)
- [color/color-no-hex — Shopify Polaris React](#color-color-no-hex-shopify-polaris-react)
- [layout/custom-property-disallowed-list — Shopify Polaris React](#layout-custom-property-disallowed-list-shopify-polaris-react)
- [conventions/custom-property-allowed-list — Shopify Polaris React](#conventions-custom-property-allowed-list-shopify-polaris-react)
- [layout/at-rule-disallowed-list — Shopify Polaris React](#layout-at-rule-disallowed-list-shopify-polaris-react)
- [conventions/selector-disallowed-list — Shopify Polaris React](#conventions-selector-disallowed-list-shopify-polaris-react)
- [layout/function-disallowed-list — Shopify Polaris React](#layout-function-disallowed-list-shopify-polaris-react)
- [layout/global-disallowed-list — Shopify Polaris React](#layout-global-disallowed-list-shopify-polaris-react)
- [legacy/at-rule-disallowed-list — Shopify Polaris React](#legacy-at-rule-disallowed-list-shopify-polaris-react)
- [legacy/function-disallowed-list — Shopify Polaris React](#legacy-function-disallowed-list-shopify-polaris-react)
- [media-queries/at-rule-disallowed-list — Shopify Polaris React](#media-queries-at-rule-disallowed-list-shopify-polaris-react)
- [media-queries/media-queries-allowed-list — Shopify Polaris React](#media-queries-media-queries-allowed-list-shopify-polaris-react)
- [media-queries/function-disallowed-list — Shopify Polaris React](#media-queries-function-disallowed-list-shopify-polaris-react)
- [motion/at-rule-disallowed-list — Shopify Polaris React](#motion-at-rule-disallowed-list-shopify-polaris-react)
- [legacy/global-disallowed-list — Shopify Polaris React](#legacy-global-disallowed-list-shopify-polaris-react)
- [motion/custom-property-disallowed-list — Shopify Polaris React](#motion-custom-property-disallowed-list-shopify-polaris-react)
- [motion/function-disallowed-list — Shopify Polaris React](#motion-function-disallowed-list-shopify-polaris-react)
- [shadow/declaration-property-unit-disallowed-list — Shopify Polaris React](#shadow-declaration-property-unit-disallowed-list-shopify-polaris-react)
- [shadow/custom-property-disallowed-list — Shopify Polaris React](#shadow-custom-property-disallowed-list-shopify-polaris-react)
- [motion/declaration-property-unit-disallowed-list — Shopify Polaris React](#motion-declaration-property-unit-disallowed-list-shopify-polaris-react)
- [motion/global-disallowed-list — Shopify Polaris React](#motion-global-disallowed-list-shopify-polaris-react)
- [shadow/function-disallowed-list — Shopify Polaris React](#shadow-function-disallowed-list-shopify-polaris-react)
- [shadow/global-disallowed-list — Shopify Polaris React](#shadow-global-disallowed-list-shopify-polaris-react)
- [space/declaration-property-unit-disallowed-list — Shopify Polaris React](#space-declaration-property-unit-disallowed-list-shopify-polaris-react)
- [space/function-disallowed-list — Shopify Polaris React](#space-function-disallowed-list-shopify-polaris-react)
- [space/custom-property-disallowed-list — Shopify Polaris React](#space-custom-property-disallowed-list-shopify-polaris-react)
- [typography/function-disallowed-list — Shopify Polaris React](#typography-function-disallowed-list-shopify-polaris-react)
- [shadow/property-disallowed-list — Shopify Polaris React](#shadow-property-disallowed-list-shopify-polaris-react)
- [typography/at-rule-disallowed-list — Shopify Polaris React](#typography-at-rule-disallowed-list-shopify-polaris-react)
- [typography/declaration-property-value-disallowed-list — Shopify Polaris React](#typography-declaration-property-value-disallowed-list-shopify-polaris-react)
- [typography/global-disallowed-list — Shopify Polaris React](#typography-global-disallowed-list-shopify-polaris-react)
- [space/global-disallowed-list — Shopify Polaris React](#space-global-disallowed-list-shopify-polaris-react)
- [typography/declaration-property-unit-disallowed-list — Shopify Polaris React](#typography-declaration-property-unit-disallowed-list-shopify-polaris-react)
- [z-index/declaration-property-value-allowed-list — Shopify Polaris React](#z-index-declaration-property-value-allowed-list-shopify-polaris-react)
- [z-index/custom-property-disallowed-list — Shopify Polaris React](#z-index-custom-property-disallowed-list-shopify-polaris-react)
- [typography/property-disallowed-list — Shopify Polaris React](#typography-property-disallowed-list-shopify-polaris-react)
- [z-index/function-disallowed-list — Shopify Polaris React](#z-index-function-disallowed-list-shopify-polaris-react)
- [z-index/global-disallowed-list — Shopify Polaris React](#z-index-global-disallowed-list-shopify-polaris-react)
---
# Foundations — Shopify Polaris React
[**Introducing Polaris** - Unified and for the web. Release Candidate](https://shopify.dev/beta/next-gen-dev-platform/polaris)
[Skip to content](https://polaris-react.shopify.com/foundations#main)
[Polaris React](https://polaris-react.shopify.com/)
🌙Search /
Foundations
===========
Polaris is the design system for the Shopify admin. It’s the shared language that guides how we build high-quality merchant experiences.
* [#### Accessibility\
\
Making commerce better for everyone means caring deeply about making quality products. A quality product should have a fantastic user experience (UX).](https://polaris-react.shopify.com/foundations/accessibility)
* [#### Formatting localized currency\
\
Currencies are formatted differently in different countries and languages.](https://polaris-react.shopify.com/foundations/formatting-localized-currency)
* [#### Information architecture\
\
Everything we create at Shopify has an underlying foundation of information architecture. If you’re a designer, a content strategist, or a UX developer, you’re already doing IA work.](https://polaris-react.shopify.com/foundations/information-architecture)
* [#### Internationalization\
\
Make commerce better for everyone by building interfaces that work everywhere. These guidelines will help you design, write, and build products that can be used in every part of the world.](https://polaris-react.shopify.com/foundations/internationalization)
* [#### Shopify experience values\
\
At Shopify, we empower commerce at a global scale. We build products, tools, and services for people to start, manage, and scale their businesses. We manage enormous complexity for commerce giants, and give new entrepreneurs the best chance to succeed.](https://polaris-react.shopify.com/foundations/experience-values)
---
# Shopify Polaris React
[**Introducing Polaris** - Unified and for the web. Release Candidate](https://shopify.dev/beta/next-gen-dev-platform/polaris)
[Skip to content](https://polaris-react.shopify.com/#main)
[Polaris React](https://polaris-react.shopify.com/)
🌙Search /
Build. Contribute. Evolve.
==========================
Shape the merchant experience for Shopify’s core product, the admin.
[### Foundations\
\
Fundamental design guidance for creating quality admin experiences](https://polaris-react.shopify.com/foundations)
[### Components\
\
Reusable elements and styles, packaged through code, for building admin interfaces](https://polaris-react.shopify.com/components)
[### Tokens\
\
Coded names that represent design decisions for color, spacing, typography, and more](https://polaris-react.shopify.com/tokens/color)
[### Icons\
\
Over 400 carefully designed icons focused on commerce and entrepreneurship](https://polaris-react.shopify.com/icons)
---
# Getting Started — Shopify Polaris React
[**Introducing Polaris** - Unified and for the web. Release Candidate](https://shopify.dev/beta/next-gen-dev-platform/polaris)
[Skip to content](https://polaris-react.shopify.com/getting-started#main)
[Polaris React](https://polaris-react.shopify.com/)
🌙Search /
Getting Started
===============
Polaris is the design system for the Shopify admin. If you’re just starting out with Polaris, here’s a list of recommended resources and guidance to get you started.
Design resources
----------------
Shopify provides [Figma community resources](https://www.figma.com/@Shopify)
for Polaris components, styles, and icons. If you are new to Figma, check out our [onboarding guide](https://www.figma.com/community/file/994263185745279952)
, or open Figma and start designing with the Polaris:
* [Component UI kit](https://www.figma.com/community/file/1293611962331823010/polaris-components)
* [Style Library](https://www.figma.com/community/file/1293614121185734569/polaris-styles)
* [Icon Library](https://www.figma.com/community/file/1293614863849914283/polaris-icons)
Development resources
---------------------
The [Shopify/polaris GitHub repo](https://github.com/Shopify/polaris)
is an open-source monorepo made up of NPM packages, VS Code extensions, and this website. To get started, learn how to install and use the Polaris:
* [React components](https://github.com/Shopify/polaris/tree/main/polaris-react#using-the-react-components)
* [Design tokens](https://github.com/Shopify/polaris/tree/main/polaris-tokens#installation)
* [VS Code extension](https://polaris-react.shopify.com/tools/polaris-for-vscode)
Tutorials
---------
#### [Build a Shopify app](https://shopify.dev/apps/getting-started/create)
In this tutorial, you'll create an app that merchants can access in the Shopify admin. You'll use an app initialization command that generates starter code for building your app, and sets up your development environment so that you can work with your app using [Shopify CLI](https://shopify.dev/apps/tools/cli)
.
Your app will use Polaris and [App Bridge](https://shopify.dev/apps/tools/app-bridge)
while following the [App Design Guidelines](https://shopify.dev/apps/design-guidelines)
.
Expand your knowledge
---------------------
Polaris provides foundational design guidance for creating good merchant experiences. Here are some recommended resources to:
* [Experience values](https://polaris-react.shopify.com/foundations/experience-values)
* [Design guidelines](https://polaris-react.shopify.com/design)
* [Content fundamentals](https://polaris-react.shopify.com/content/fundamentals)
On this page
------------
* [Design resources](https://polaris-react.shopify.com/getting-started#design-resources)
* [Development resources](https://polaris-react.shopify.com/getting-started#development-resources)
* [Tutorials](https://polaris-react.shopify.com/getting-started#tutorials)
* [Expand your knowledge](https://polaris-react.shopify.com/getting-started#expand-your-knowledge)
---
# Content — Shopify Polaris React
[**Introducing Polaris** - Unified and for the web. Release Candidate](https://shopify.dev/beta/next-gen-dev-platform/polaris)
[Skip to content](https://polaris-react.shopify.com/content#main)
[Polaris React](https://polaris-react.shopify.com/)
🌙Search /
Content
=======
How to use content to build a world-class user experience
* [#### Fundamentals\
\
Designing content for experiences](https://polaris-react.shopify.com/content/fundamentals)
* [#### Grammar\
\
For anyone who writes for the admin](https://polaris-react.shopify.com/content/grammar-and-mechanics)
* [#### Error messages\
\
Make it clear what went wrong and how to fix it](https://polaris-react.shopify.com/content/error-messages)
* [#### Naming\
\
What to consider as you name products or features](https://polaris-react.shopify.com/content/naming)
* [#### Alternative text\
\
Build inclusive experiences for merchants who use screen readers](https://polaris-react.shopify.com/content/alternative-text)
* [#### Inclusive language\
\
Make commerce better for everyone by writing inclusively](https://polaris-react.shopify.com/content/inclusive-language)
---
# Polaris 101 — Shopify Polaris React
[**Introducing Polaris** - Unified and for the web. Release Candidate](https://shopify.dev/beta/next-gen-dev-platform/polaris)
[Skip to content](https://polaris-react.shopify.com/getting-started/polaris-101#main)
[Polaris React](https://polaris-react.shopify.com/)
Search /
Polaris 101
===========
The Polaris design system is used by designers and developers to build world-class Shopify admin experiences.
What’s the Shopify admin?
-------------------------
Merchants set up their store, configure settings, and manage their business using the admin. It includes core aspects of the merchant’s business, including orders, products, and customers.

What is Polaris?
----------------
Polaris is the design system for the Shopify admin. It’s the shared language that guides how we build high-quality merchant experiences.
The design system is made up of design guidance, code libraries, development opinions, and API documentation on how to build merchant experiences for the Shopify admin.
Who is Polaris for?
-------------------
Polaris is used both internally at Shopify and externally by app developers and designers.
What are Shopify apps?
----------------------
The admin includes installable apps that are distributed through the Shopify App Store. They enable merchants to add functionality to their stores without leaving the familiar environment of the admin.
By building with Polaris and [App Bridge](https://shopify.dev/apps/tools/app-bridge)
and following the [App Design Guidelines](https://shopify.dev/apps/design-guidelines)
, you'll create a streamlined experience with the rest of the Shopify admin.
On this page
------------
---
# Accessibility — Shopify Polaris React
[**Introducing Polaris** - Unified and for the web. Release Candidate](https://shopify.dev/beta/next-gen-dev-platform/polaris)
[Skip to content](https://polaris-react.shopify.com/foundations/accessibility#main)
[Polaris React](https://polaris-react.shopify.com/)
Search /
Accessibility
=============
Making commerce better for everyone means caring deeply about making quality products. A quality product should have a fantastic user experience (UX).
This includes:
* A beautiful and functional design
* Consistent and useful [copy](https://polaris-react.shopify.com/content/product-content)
* Principles of [universal design](https://en.wikipedia.org/wiki/Universal_design)
and inclusivity
* * *
Usable for everyone
-------------------
It’s important that Shopify products—and [Partner](https://www.shopify.ca/partners)
products—are usable and useful to everyone.
Everyone is a pretty big group. It includes our merchants, their customers, our developer partners, our employees, and the greater tech community at large. That also includes all members of our community who have disabilities.
Disabilities may affect how people move, see, hear, communicate, learn, understand, and process information. As a result, it’s important to consider how to design and develop your product to support a wide range of needs and experiences.
In the United States, as many as 1 in 4 adults has at least 1 disability \[Source: [CDC](https://www.cdc.gov/media/releases/2018/p0816-disability.html)\
\]. In Canada, the estimate is 22%, and elsewhere in the world the estimate is closer to 1 in 7 \[Source: [Statistics Canada](https://www150.statcan.gc.ca/n1/pub/11-627-m/11-627-m2018035-eng.htm)\
, [World Bank](https://www.worldbank.org/en/topic/disability)\
\].
* * *
Building inclusive experiences
------------------------------
Using our [components](https://polaris-react.shopify.com/components)
is a way to improve accessibility and consistency when building products for Shopify.
* The component library in this style guide includes code we can use across applications
* This component code includes accessible markup
* Since the code exists in a single component that gets reused, it’s easier to update and fix any bugs
The build-it-once, use-it-everywhere model means the accessibility knowledge of the designers and developers who build these components is available to all of Shopify and our partners. Because of this, merchants get a consistent experience that can be leveraged into accessible products.
Many accessibility features come free in the components. But, it’s important to make sure that components are integrated in a way that doesn't create unforeseen accessibility barriers. Depending how components are used, there may be more design and implementation considerations. Be sure to test user task flows post integration.
### Managing focus to support merchant workflows
Don’t programmatically move focus to new content without merchant input. Polaris components that use controls to display overlays, such as modals and popovers, manage focus automatically.
Do
* When a merchant activates a link that goes elsewhere in the page, move focus to that content
* When a merchant must access an overlay, move focus to it
* When a merchant submits a form that results in an error, move focus to the error message
Don't
* Move focus when content updates in the background
* Move focus when the user is actively working elsewhere on the page
The only case where focus should be managed without the merchant’s okay is when the merchant needs to be interrupted because they cannot continue their current workflow.
### Limiting non-standard interactions
Merchants will expect to interact with controls and content in ways that follow the defaults for their browser, platform, and assistive technologies. Introducing non-standard features can give merchants better ways of accomplishing tasks, but they can also create barriers.
For example, merchants who rely on the keyboard will expect that buttons can be activated with the enter/return key or the space key. If buttons are programmed to be used with different keys, merchants will need to be instructed on how to use them.
Before designing or building custom features that use non-standard controls or interactions, first consider whether the goal can be met using native features.
If non-standard interactions _are_ required:
* Carefully follow guidelines and best practices for designing, building, and testing custom features on your platform
* Give merchants clear instructions for using the custom feature
* Provide an additional, standard way to accomplish the task
### Assistive technology support
Our components are tested for accessibility with automated and manual techniques. Merchants should expect to be able to access features built with our components using modern assistive technologies. These include native and third-party tools like:
* Screen readers
* Speech recognition programs
* Supports for low vision and color blindness
* Alternative keyboards
* Switch devices
* Tools for readability
### Coding standards
Polaris components start with web standards for HTML, CSS, and JavaScript. Features from the Accessible Rich Internet Applications (WAI-ARIA or ARIA) specification are used to build functionality that is not available in native HTML.
### Alternative text
To help people who rely on assistive technologies, such as a screen reader or other text to speech programs, our components use [alternative text](https://polaris-react.shopify.com/content/alternative-text)
for icons and images used to convey information and actions (like buttons and links).
### Meeting the Web Content Accessibility Guidelines (WCAG)
Polaris targets WCAG 2.1 Level A and Level AA success criteria, and seeks to provide a highly usable experience for everyone.
For more information, see the following resources:
* [WCAG 2.1](https://www.w3.org/TR/WCAG21/)
* [ARIA 1.1](https://www.w3.org/TR/wai-aria-1.1/)
* [Shopify's statement of commitment to accessibility](https://www.shopify.com/accessibility)
### Feedback
Sometimes, building accessible and inclusive experiences can be difficult. If we’ve made any mistakes in this style guide, please [reach out by creating a GitHub issue](https://github.com/Shopify/polaris-react/issues)
and help us make it better.
On this page
------------
---
# Design — Shopify Polaris React
[**Introducing Polaris** - Unified and for the web. Release Candidate](https://shopify.dev/beta/next-gen-dev-platform/polaris)
[Skip to content](https://polaris-react.shopify.com/design#main)
[Polaris React](https://polaris-react.shopify.com/)
Search /
Design
======
Design principles serve as guiding notions that shape the design of the Shopify admin, with Polaris providing support in implementing these principles effectively.
* [#### Pro design language\
\
Efficiency, intuition, and style combined to empower merchants with data-rich views, action-driven interfaces, and dynamic interactions.](https://polaris-react.shopify.com/design/pro-design-language)
* [#### Color\
\
Color highlights important areas, communicates status, urgency, and directs attention.](https://polaris-react.shopify.com/design/colors)
* [#### Depth\
\
Depth introduces a sense of realism, helps establish visual hierarchy, and creates focus.](https://polaris-react.shopify.com/design/depth)
* [#### Icons\
\
Icons enhance an experience by providing intuitive and efficient navigation, conveying information concisely, and making it more visually appealing.](https://polaris-react.shopify.com/design/icons)
* [#### Layout\
\
Layout determines the placement, positioning, and organization of various components within the UI, such as buttons, menus, content sections, and other visual elements.](https://polaris-react.shopify.com/design/layout)
* [#### Motion\
\
Motion brings dynamism to an interface, offers visual feedback, and aids merchants understanding the outcomes of their actions.](https://polaris-react.shopify.com/design/motion)
* [#### Typography\
\
Typography is the art of arranging type in ways that provides innate hierarchy to UI.](https://polaris-react.shopify.com/design/typography)
* [#### Data visualizations\
\
Visualizations surface patterns in data, and provide immediate answers to a single, specific question.](https://polaris-react.shopify.com/design/data-visualizations)
* [#### Illustrations\
\
The Shopify admin uses a precise illustration style to help merchants quickly and clearly understand how things work across every experience.](https://polaris-react.shopify.com/design/illustrations)
* [#### Interaction states\
\
Interaction states communicate the status of an element in the interface, establish confidence once an action is taken, and suggest the ability (or inability) to interact with the element.](https://polaris-react.shopify.com/design/interaction-states)
* [#### Sounds\
\
We use sound to communicate information and to enhance how merchants experience the Shopify admin. Sound patterns make interactions easier and more predictable.](https://polaris-react.shopify.com/design/sounds)
---
# Patterns — Shopify Polaris React
[**Introducing Polaris** - Unified and for the web. Release Candidate](https://shopify.dev/beta/next-gen-dev-platform/polaris)
[Skip to content](https://polaris-react.shopify.com/patterns#main)
[Polaris React](https://polaris-react.shopify.com/)
Search /
Patterns
========
Preferred solutions to common merchant goals in the admin.
* [\
\
#### App settings layout\
\
Scan and find groups of settings in apps](https://polaris-react.shopify.com/patterns/app-settings-layout)
* [\
\
#### Card layout\
\
Standardized card layout gives merchants a content structure to rely on.](https://polaris-react.shopify.com/patterns/card-layout)
* [\
\
#### Common actions\
\
Standardizing recurring actions gives merchants a predictable way to complete common tasks.](https://polaris-react.shopify.com/patterns/common-actions)
* [\
\
#### Date picking\
\
Select a date or a date range](https://polaris-react.shopify.com/patterns/date-picking)
* [\
\
#### New features\
\
Highlight new features for merchants](https://polaris-react.shopify.com/patterns/new-features)
* [\
\
#### Resource details layout\
\
Create, view, and edit resource objects](https://polaris-react.shopify.com/patterns/resource-details-layout)
* [\
\
#### Resource index layout\
\
Organize and take action on resource objects](https://polaris-react.shopify.com/patterns/resource-index-layout)
Archived documentation
----------------------
These guidelines are safe to use and will be updated to the new documentation format in the near future.
* [#### Loading\
\
Navigating the Shopify admin should be fast, meaningful, and focused. Intentional loading states deliver a continuous flow for merchants.](https://polaris-react.shopify.com/patterns-legacy/loading)
* [#### New badge\
\
The New badge can be used to inform merchants about the release of a feature that creates new value. It should be used sparingly and for a short time frame.](https://polaris-react.shopify.com/patterns-legacy/new-badge)
* [#### Pickers\
\
Picker experiences help merchants browse, find, and select from multiple options. Use them for selecting locations, customer segments, and more.](https://polaris-react.shopify.com/patterns-legacy/pickers)
* [#### Text fields\
\
Text fields combine the field label (the title) and the input area. Inputs can vary from typed text to URLs to date pickers.](https://polaris-react.shopify.com/patterns-legacy/text-fields)
---
# Components — Shopify Polaris React
[**Introducing Polaris** - Unified and for the web. Release Candidate](https://shopify.dev/beta/next-gen-dev-platform/polaris)
[Skip to content](https://polaris-react.shopify.com/components#main)
[Polaris React](https://polaris-react.shopify.com/)
Search /
Components
==========
Components are the reusable building blocks for creating Shopify admin experiences.
Actions
-------
* [\
\
#### Account connection\
\
Used for connecting or disconnecting a store to various accounts, like Facebook for the sales channel.](https://polaris-react.shopify.com/components/actions/account-connection)
* [\
\
#### Button\
\
Used primarily for actions like 'Add', 'Close', 'Cancel', or 'Save'. Plain buttons are used for less important actions.](https://polaris-react.shopify.com/components/actions/button)
* [\
\
#### Button group\
\
Displays multiple related actions stacked or in a horizontal row for arrangement and spacing.](https://polaris-react.shopify.com/components/actions/button-group)
Layout and structure
--------------------
* [\
\
#### Bleed\
\
Applies negative margin to a layout, extending it to the edge of the screen on small screens.](https://polaris-react.shopify.com/components/layout-and-structure/bleed)
* [\
\
#### Block stack\
\
Use to display children vertically and horizontally with full width by default. Based on CSS Flexbox.](https://polaris-react.shopify.com/components/layout-and-structure/block-stack)
* [\
\
#### Box\
\
Box is the most primitive layout component. It’s a way to access Polaris design tokens.](https://polaris-react.shopify.com/components/layout-and-structure/box)
* [\
\
#### 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.](https://polaris-react.shopify.com/components/layout-and-structure/callout-card)
* [\
\
#### Card\
\
Used to group similar concepts and tasks together for easier scanning and reading.](https://polaris-react.shopify.com/components/layout-and-structure/card)
* [\
\
#### Divider\
\
Use to separate or group content.](https://polaris-react.shopify.com/components/layout-and-structure/divider)
* [\
\
#### 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.](https://polaris-react.shopify.com/components/layout-and-structure/empty-state)
* [\
\
#### Form layout\
\
Manages the layout of all forms and fields within it. Used for the layout of new forms and managing the layout of all forms.](https://polaris-react.shopify.com/components/layout-and-structure/form-layout)
* [\
\
#### Grid\
\
Create complex layouts based on CSS Grid.](https://polaris-react.shopify.com/components/layout-and-structure/grid)
* [\
\
#### Inline grid\
\
Use to lay out children horizontally with equal gap between columns. Based on CSS Grid.](https://polaris-react.shopify.com/components/layout-and-structure/inline-grid)
* [\
\
#### Inline stack\
\
Use to display children horizontally in a row. Based on CSS Flexbox.](https://polaris-react.shopify.com/components/layout-and-structure/inline-stack)
* [\
\
#### Layout\
\
A structural component used to group other components. Creates consistent spacing and helps layout stack and scale responsively.](https://polaris-react.shopify.com/components/layout-and-structure/layout)
* [\
\
#### Media card\
\
Provides a container for introductory or highlight information. Often used in a grid to present related content.](https://polaris-react.shopify.com/components/layout-and-structure/media-card)
* [\
\
#### Page\
\
Used to build the layout of a page in the Shopify admin. A flexible container for composing pages consistently.](https://polaris-react.shopify.com/components/layout-and-structure/page)
Selection and input
-------------------
* [\
\
#### 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.](https://polaris-react.shopify.com/components/selection-and-input/autocomplete)
* [\
\
#### 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.](https://polaris-react.shopify.com/components/selection-and-input/checkbox)
* [\
\
#### 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.](https://polaris-react.shopify.com/components/selection-and-input/choice-list)
* [\
\
#### Color picker\
\
Allows merchants to choose a color visually, or by entering a hex value.](https://polaris-react.shopify.com/components/selection-and-input/color-picker)
* [\
\
#### Combobox\
\
Combobox is an accessible autocomplete input that enables merchants to filter a list of options and select one or more values.](https://polaris-react.shopify.com/components/selection-and-input/combobox)
* [\
\
#### Date picker\
\
Date pickers let merchants choose dates from a visual calendar that’s consistently applied wherever dates need to be selected across Shopify.](https://polaris-react.shopify.com/components/selection-and-input/date-picker)
* [\
\
#### 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.](https://polaris-react.shopify.com/components/selection-and-input/drop-zone)
* [\
\
#### Filters\
\
A composite component that filters the items of a list or table.](https://polaris-react.shopify.com/components/selection-and-input/filters)
* [\
\
#### Form\
\
A wrapper component that handles the submission of forms.](https://polaris-react.shopify.com/components/selection-and-input/form)
* [\
\
#### 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.](https://polaris-react.shopify.com/components/selection-and-input/index-filters)
* [\
\
#### 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.](https://polaris-react.shopify.com/components/selection-and-input/inline-error)
* [\
\
#### Radio button\
\
Use radio buttons to present each item in a list of options where merchants must make a single selection.](https://polaris-react.shopify.com/components/selection-and-input/radio-button)
* [\
\
#### 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).](https://polaris-react.shopify.com/components/selection-and-input/range-slider)
* [\
\
#### 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.](https://polaris-react.shopify.com/components/selection-and-input/select)
* [\
\
#### 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.](https://polaris-react.shopify.com/components/selection-and-input/tag)
* [\
\
#### 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.](https://polaris-react.shopify.com/components/selection-and-input/text-field)
Images and icons
----------------
* [\
\
#### Avatar\
\
Used to show a thumbnail representation of an individual or business in the interface.](https://polaris-react.shopify.com/components/images-and-icons/avatar)
* [\
\
#### Icon\
\
Used to visually communicate core parts of the product and available actions, acting as wayfinding tools.](https://polaris-react.shopify.com/components/images-and-icons/icon)
* [\
\
#### Keyboard key\
\
Used to educate merchants about keyboard shortcuts.](https://polaris-react.shopify.com/components/images-and-icons/keyboard-key)
* [\
\
#### Thumbnail\
\
Used as a visual anchor and identifier for an object, along with text to provide context.](https://polaris-react.shopify.com/components/images-and-icons/thumbnail)
* [\
\
#### Video thumbnail\
\
A clickable placeholder image that opens a video player within a modal or full screen when clicked.](https://polaris-react.shopify.com/components/images-and-icons/video-thumbnail)
Feedback indicators
-------------------
* [\
\
#### Badge\
\
Used to inform merchants of the tone of an object or an action taken.](https://polaris-react.shopify.com/components/feedback-indicators/badge)
* [\
\
#### Banner\
\
Informs merchants about important changes or persistent conditions in a prominent way.](https://polaris-react.shopify.com/components/feedback-indicators/banner)
* [\
\
#### Exception list\
\
Helps merchants notice important, standout information that adds extra context to a task.](https://polaris-react.shopify.com/components/feedback-indicators/exception-list)
* [\
\
#### Progress bar\
\
Used to visually represent the completion of a task or operation.](https://polaris-react.shopify.com/components/feedback-indicators/progress-bar)
* [\
\
#### Skeleton body text\
\
Provides a low fidelity representation of content before it appears, improving perceived load times.](https://polaris-react.shopify.com/components/feedback-indicators/skeleton-body-text)
* [\
\
#### Skeleton display text\
\
Provides a low fidelity representation of content before it appears, improving perceived load times.](https://polaris-react.shopify.com/components/feedback-indicators/skeleton-display-text)
* [\
\
#### Skeleton page\
\
Used with other skeleton loading components to provide a low fidelity representation of the UI before content appears.](https://polaris-react.shopify.com/components/feedback-indicators/skeleton-page)
* [\
\
#### Skeleton tabs\
\
Provides a low fidelity representation of content before it appears, improving perceived load times.](https://polaris-react.shopify.com/components/feedback-indicators/skeleton-tabs)
* [\
\
#### Skeleton thumbnail\
\
Provides a low fidelity representation of an image before it appears, improving perceived load times.](https://polaris-react.shopify.com/components/feedback-indicators/skeleton-thumbnail)
* [\
\
#### Spinner\
\
Used to notify merchants that their action is being processed. Used for content that can’t be represented with skeleton loading components.](https://polaris-react.shopify.com/components/feedback-indicators/spinner)
Typography
----------
* [\
\
#### Text\
\
Typography helps establish hierarchy and communicate important content by creating clear visual patterns.](https://polaris-react.shopify.com/components/typography/text)
Tables
------
* [\
\
#### Data table\
\
Used to organize and display all information from a data set. Aimed to be as simple as possible for merchants.](https://polaris-react.shopify.com/components/tables/data-table)
* [\
\
#### 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.](https://polaris-react.shopify.com/components/tables/index-table)
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.](https://polaris-react.shopify.com/components/lists/action-list)
* [\
\
#### Description list\
\
Used to present pairs of related information, like terms and definitions, or names and values, in a list format.](https://polaris-react.shopify.com/components/lists/description-list)
* [\
\
#### List\
\
Lists display a set of related text-only content. Each list item begins with a bullet or a number.](https://polaris-react.shopify.com/components/lists/list)
* [\
\
#### Listbox\
\
A Listbox is a vertical list of interactive options, with room for icons, descriptions, and other elements.](https://polaris-react.shopify.com/components/lists/listbox)
* [\
\
#### 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.](https://polaris-react.shopify.com/components/lists/option-list)
* [\
\
#### 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.](https://polaris-react.shopify.com/components/lists/resource-item)
* [\
\
#### 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.](https://polaris-react.shopify.com/components/lists/resource-list)
Navigation
----------
* [\
\
#### Footer help\
\
Footer help is used to refer merchants to more information related to the product or feature they’re using.](https://polaris-react.shopify.com/components/navigation/footer-help)
* [\
\
#### Link\
\
Links take users to another place, and usually appear within or directly following a sentence.](https://polaris-react.shopify.com/components/navigation/link)
* [\
\
#### 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.](https://polaris-react.shopify.com/components/navigation/pagination)
* [\
\
#### Tabs\
\
Used to alternate among related views within the same context.](https://polaris-react.shopify.com/components/navigation/tabs)
Overlays
--------
* [\
\
#### Popover\
\
Small overlays that open on demand and close when the merchant interacts with any other part of Shopify. Used to surface secondary information or actions.](https://polaris-react.shopify.com/components/overlays/popover)
* [\
\
#### 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.](https://polaris-react.shopify.com/components/overlays/tooltip)
Utilities
---------
* [\
\
#### App provider\
\
App provider is a required component that enables sharing global settings throughout the hierarchy of your application.](https://polaris-react.shopify.com/components/utilities/app-provider)
* [\
\
#### Collapsible\
\
Hides content and allows merchants to expand it. Used to hide optional settings, information, and actions.](https://polaris-react.shopify.com/components/utilities/collapsible)
* [\
\
#### Scrollable\
\
Used in components with too much content for the available vertical space. Embeds long-form content in components like modals and popovers.](https://polaris-react.shopify.com/components/utilities/scrollable)
Deprecated
----------
* [\
\
#### Caption\
\
Deprecated\
\
Caption text is smaller than the recommended size for general reading. Used in graphs, timestamps, or as secondary text.](https://polaris-react.shopify.com/components/deprecated/caption)
* [\
\
#### Contextual save bar\
\
Deprecated\
\
Informs merchants of their options once they have made changes to a form on the page or while creating a new object.](https://polaris-react.shopify.com/components/deprecated/contextual-save-bar)
* [\
\
#### Display text\
\
Deprecated\
\
Display styles make a bold visual statement. Used for visual storytelling, marketing content, or capturing attention.](https://polaris-react.shopify.com/components/deprecated/display-text)
* [\
\
#### Frame\
\
Deprecated\
\
Creates the structure of the Shopify admin. All of the main sections of the admin are nested in the frame.](https://polaris-react.shopify.com/components/deprecated/frame)
* [\
\
#### Fullscreen bar\
\
Deprecated\
\
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.](https://polaris-react.shopify.com/components/deprecated/fullscreen-bar)
* [\
\
#### Heading\
\
Deprecated\
\
Used as the titles of each major section of a page in the interface, like in card components.](https://polaris-react.shopify.com/components/deprecated/heading)
* [\
\
#### Legacy card\
\
Deprecated\
\
Legacy version of the Card component. Used to group similar concepts and tasks together for easier scanning and reading.](https://polaris-react.shopify.com/components/deprecated/legacy-card)
* [\
\
#### Legacy filters\
\
Deprecated\
\
Legacy version of the Filters component. Used to filter the items of a list or table.](https://polaris-react.shopify.com/components/deprecated/legacy-filters)
* [\
\
#### Legacy stack\
\
Deprecated\
\
Legacy version of the Stack component. Used for layout of a horizontal row of components or vertical centering.](https://polaris-react.shopify.com/components/deprecated/legacy-stack)
* [\
\
#### Legacy tabs\
\
Deprecated\
\
Used to alternate among related views within the same context.](https://polaris-react.shopify.com/components/deprecated/legacy-tabs)
* [\
\
#### Loading\
\
Deprecated\
\
Used to indicate to merchants that a page is loading or an upload is processing.](https://polaris-react.shopify.com/components/deprecated/loading)
* [\
\
#### Modal\
\
Deprecated\
\
Used to interrupt merchants with urgent information, details, or actions.](https://polaris-react.shopify.com/components/deprecated/modal)
* [\
\
#### Navigation\
\
Deprecated\
\
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.](https://polaris-react.shopify.com/components/deprecated/navigation)
* [\
\
#### Page actions\
\
Deprecated\
\
Allows merchants to take key actions at the bottom of specific pages in the interface.](https://polaris-react.shopify.com/components/deprecated/page-actions)
* [\
\
#### Setting toggle\
\
Deprecated\
\
Used to control a feature or option that can be turned on or off.](https://polaris-react.shopify.com/components/deprecated/setting-toggle)
* [\
\
#### Sheet\
\
Deprecated\
\
A large container providing actions and information contextual to the page without interrupting flow like a modal.](https://polaris-react.shopify.com/components/deprecated/sheet)
* [\
\
#### Subheading\
\
Deprecated\
\
Used for the title of any sub-sections in top-level page sections.](https://polaris-react.shopify.com/components/deprecated/subheading)
* [\
\
#### Text container\
\
Deprecated\
\
Used to wrap text elements like paragraphs, headings, and lists for vertical spacing.](https://polaris-react.shopify.com/components/deprecated/text-container)
* [\
\
#### Text style\
\
Deprecated\
\
Enhances text with additional visual meaning, like using subdued text to de-emphasize it.](https://polaris-react.shopify.com/components/deprecated/text-style)
* [\
\
#### Toast\
\
Deprecated\
\
A non-disruptive message that provides quick feedback on the outcome of an action.](https://polaris-react.shopify.com/components/deprecated/toast)
* [\
\
#### Top bar\
\
Deprecated\
\
Appears at the top of the page and is used to brand and navigate major applications areas.](https://polaris-react.shopify.com/components/deprecated/top-bar)
* [\
\
#### Visually hidden\
\
Deprecated\
\
Used when an element needs to be available to assistive technology but otherwise hidden.](https://polaris-react.shopify.com/components/deprecated/visually-hidden)
---
# Component lifecycle — Shopify Polaris React
[**Introducing Polaris** - Unified and for the web. Release Candidate](https://shopify.dev/beta/next-gen-dev-platform/polaris)
[Skip to content](https://polaris-react.shopify.com/getting-started/components-lifecycle#main)
[Polaris React](https://polaris-react.shopify.com/)
Search /
Component lifecycle
===================
Polaris components move through a series of stages throughout their lifecycle. Within each stage, a component must meet a set of requirements.
### Feedback and suggestions
Have feedback, a question, or suggestion? [Create an issue](https://github.com/Shopify/polaris/issues/new)
during any stage of a component’s lifecycle.
* * *
Alpha
-----
The component is a work in progress and ready for exploratory usage, with breaking changes expected. During this stage, we’re being critical about understanding the purpose of the component and what problem it’s trying to solve. If the purpose is unclear, we may decide not to move forward with the component and it could be removed without warning.
### Requirements for alpha
* Has a clear purpose and rationale for why it belongs in Polaris
* Uses Polaris [tokens](https://polaris.shopify.com/tokens)
with no references to any hard-coded static values
* Designed with responsiveness in mind and can adapt across [breakpoints](https://polaris.shopify.com/tokens/breakpoints)
* Meets known [accessibility](https://polaris.shopify.com/foundations/accessibility)
requirements like: contrast, interactive states, touch target size, etc.
* In progress documentation exists that includes the list of props with some examples
* Documentation includes examples in Storybook
* The component has 100% test coverage
### What to expect during alpha
* Usage is being evaluated, and may not progress to beta. Evaluation includes any necessary research and data that supports why the component belongs in Polaris.
* Components could be changed completely, or removed from the system
* Feedback is highly recommended and encouraged, [Create an issue](https://github.com/Shopify/polaris/issues/new)
* * *
Beta
----
The component moves to beta once there’s a clear understanding of the problem and we’re confident in the solution. The focus of this stage is all about testing in enough environments to make sure the component is bug free.
Ready for wider adoption, encouraged for most cases. Breaking changes are possible in minor version updates.
### Requirements for beta
* Used multiple times in production (Shopify admin)
* Meets all [accessibility](https://polaris.shopify.com/foundations/accessibility)
requirements for our use cases
* Usage guidelines and documentation covers common use cases
* Reviewed and tested in production by designers and developers
* Figma components available in the Polaris Components file
### What to expect during beta
* Work is being done to move to Stable
* Manual and automated migration guidance is being worked on
Stable
------
The component is bug free and works in most, if not all, environments. It’s ready for full adoption, with long-term support expected.
### Requirements for stable
* The API is stable, with no breaking changes until the next major release (if necessary)
* Usability testing and feedback has been gathered on UX and DX
* Documentation exists for component props, variants, accessibility guidelines, and usage
* Manual and automated migration documentation exists
* * *
Legacy
------
The component is stable and has been supported in at least one past major release, but there are plans to replace its functionality with a new component or a combination of new components. Usage of legacy components is not discouraged, with the caveat that it will be deprecated and replaced in the next major release.
### Requirements for legacy components
* Documentation exists for the legacy component and includes any alternative components
* The deprecation date has been announced and is at least one month away from the release date of the package that deprecated the component
* Manual and automated migration paths are documented and have been available for at least one month
* * *
Deprecated
----------
The component will be removed and should be avoided.
### Requirements for deprecation
* Documentation exists for the deprecation and includes any alternative components
* The component includes deprecation warnings when used
* The removal date has been announced and is at least one month away from the release date of the package that removes the component
* Manual and automated migration paths are documented and have been available for at least one month
On this page
------------
---
# Formatting localized currency — Shopify Polaris React
[**Introducing Polaris** - Unified and for the web. Release Candidate](https://shopify.dev/beta/next-gen-dev-platform/polaris)
[Skip to content](https://polaris-react.shopify.com/foundations/formatting-localized-currency#main)
[Polaris React](https://polaris-react.shopify.com/)
Search /
Formatting localized currency
=============================
Currencies are formatted differently in different countries and languages.
There’s a currency formatting framework to:
* Help more merchants sell globally
* Localize currency formatting for merchants and customers everywhere
* Unify the display of mixed currencies to help merchants manage multiple currency stores
* Implement the formatting through APIs
* * *
Definitions
-----------
A store can have more than one type of currency and currency format.
### Store currency
The main currency of the store and the Shopify default. All sales and reports are shown in the store currency.
### Non-store currency
Any other type of currency is called “non-store currency”. Types of non-store currency include:
* Presentment currency: The type of currency that is presented to buyers in a merchant’s store. For multi-currency stores, it can be different from store currency.
* Payout currency: The type of currency used to pay merchants for their sales. For multi-currency stores, it can be different from store currency.
* Billing currency: The type of currency used to bill merchants for themes, app purchases, and monthly subscriptions. Billing currency is in USD only, but might include local currencies for tax purposes.
### Short format
Includes the currency symbol and currency value. This format is used for currency that merchants are familiar with.
Examples: $12.50; 12,50 €
### Explicit format
Includes the currency symbol, currency value, and ISO code (for example, “USD” and “CAD”). Best used for currency that merchants aren’t familiar with and don’t expect to see.
Examples: $12.50 CAD; 12,50 € EUR
* * *
Aligning with global standards
------------------------------
Shopify uses [Common Locale Database Repository (CLDR)](http://cldr.unicode.org/)
for localization formatting for currency, date, time, and amount.
* It’s the recognized international standard
* It automatically formats numbers and currency based on the merchant’s locale
* The repository is maintained by a third party
CLDR determines:
* Whether the currency symbol appears before or after the amount (for example, $250, 250 USD, 250 $)
* Whether decimals are used (for example, there are no “cents” in Japanese yen)
* Whether the decimal sign is a period or a comma (for example, 37,50 or 37.50)
* How to group numbers (for example, 10,000 or 1,0000, or using spaces)
CLDR doesn’t determine the appropriate level of detail shown in different contexts. For example, it can’t determine when to show the currency symbol and value ([short format](https://polaris-react.shopify.com/foundations/formatting-localized-currency#short-format)
), or the currency symbol, value, and ISO code ([explicit format](https://polaris-react.shopify.com/foundations/formatting-localized-currency#explicit-format)
).
Though short format is more efficient, it’s important to provide clarity for merchants who deal with unfamiliar currencies in multi-currency stores. In those cases, use explicit format.
* * *
Design guidelines
-----------------
Because CLDR formatting is limited, these guidelines will help you choose the appropriate level of currency detail to display in a multi-currency context.
### Merchants
#### Store currency

Do
Default to [short format](https://polaris-react.shopify.com/foundations/formatting-localized-currency#short-format)
.

Don't
Use [explicit format](https://polaris-react.shopify.com/foundations/formatting-localized-currency#explicit-format)
except when presenting store currency within in a mixed-currency context.
#### Non-store currency
* Use explicit format when showing total amounts, an amount within a button, or in a paragraph
* Use short format when showing non-total amounts with total amounts

This example shows a scenario where the presentment currency is in USD, which is different than the store currency. The non-total amounts in the paid status card are in short format, and the total amounts are in explicit format.

This example shows a scenario refunding an order that’s in a non-store currency.

This example illustrates the use of short format for non-total amounts and explicit format for total amounts in a data table.
#### Negative amount display
Always place the negative symbol before the currency and amount in either format.
Do
* \-$4.20
* \-12,50 €
Don't
* $-4.20
* 12,50 €-
### Customers
* Default to explicit format whenever prices are customer-facing. Use short format for unit prices, itemized prices, and installment prices.
* If there are enough indicators to let customers know which currency they’re looking at, short format may be sufficient. When using short format, make sure to always use explicit format for cart total, checkout total, and notification totals.

This example shows the use of short format for installment prices.

This example shows the use of short format for unit prices.

This example shows the use of short format for itemized prices.
* * *
Guiding questions when making design decisions
----------------------------------------------
Use the following questions to guide you when making decisions about currency formatting.
**Does the merchant know which currency they’re looking at?**
* Which currency do they expect to see?
* Do they know which currency their orders are in if they have a multi-currency store?
**Does the currency format support the merchant’s main task?**
* Is the main task scanning, comparing and analyzing, or taking an action (for example, a refund)?
**Are there enough details to make an informed decision?**
* For example, do they know the currency of their non-store currency order refund?
* Can they distinguish between the sales report and payout summary if the store currency and payout currency are different?
**Can the UI be simplified without creating confusion?**
We don’t want to show [explicit format](https://polaris-react.shopify.com/foundations/formatting-localized-currency#explicit-format)
everywhere and for every task.
* How can we make currency formatting both simple and accurate?
* * *
Design tips
-----------
Mock up a scenario where the store, presentment, payout, and billing currencies are different. This scenario is becoming more common as more merchants start selling globally.
### Use currencies that share the same symbol to test for clarity
USD, CAD, AUD, HKD, SGD are just a few of the many currencies that share the same symbol “$”.
### Use Japanese Yen (JPY) amount to test currency length and space constraints
1 USD is approximately 100 JPY. If there is enough space for the JPY amount, it should work for most other major currencies.
### When in doubt, let the guiding questions help you make a decision
The guiding questions are meant to help make merchant-focused decisions about which format to use when the use case is unclear.
* * *
Major currencies in their local formats
---------------------------------------
This table shows commonly-used currencies in short and explicit formats.
| Currency | Locale | Short format | Explicit format |
| --- | --- | --- | --- |
| **US Dollar ($, USD)** | en-US | $12.50 | $12.50 USD |
| **Canadian Dollar ($, CAD)** | en-CA | $12.50 | $12.50 CAD |
| | fr-CA | 12,50 $ | 12,50 $ CAD |
| **Australian Dollar ($, AUD)** | en-AU | $12.50 | $12.50 AUD |
| **Euro (€, EUR)** | de-DE, fr-FR | 12,50 € | 12,50 € EUR |
| | en-IE | €12.50 | €12.50 EUR |
| | nl-NL | €12,50 | €12,50 EUR |
| **British Pounds (£, GBP)** | en-GB | £12.50 | £12.50 GBP |
| **Japanese Yen (¥, JPY)** | ja-JP | ¥1250 | ¥1250 JPY |
| **New Zealand Dollar ($, NZD)** | en-NZ | $12.50 | $12.50 NZD |
| **Hong Kong Dollar ($, HKD)** | zh-HK | $12.50 | $12.50 HKD |
| **Singapore Dollar ($, SGD)** | zh-SG | $12.50 | $12.50 SGD |
| **Danish Krone (Kr, DKK)** | da-DK | 12,50 kr. | 12,50 kr. DKK |
* * *
Implementation
--------------
To format currency in a React component, use the [Shopify/react-i18n](https://github.com/Shopify/quilt/tree/master/packages/react-i18n)
library’s formatCurrency method. You can select either short or explicit formatting by setting the form option as shown in the code example below.
Example
import {useI18n} from '@shopify/react-i18n';
const [i18n] = useI18n();
i18n.locale = 'de-AT';
const eurDeAt = i18n.formatCurrency(price, {
currency: 'EUR',
form: 'short',
});
const eurDeAtExp = i18n.formatCurrency(price, {
currency: 'EUR',
form: 'explicit',
});
On this page
------------
---
# Building with Polaris — Shopify Polaris React
[**Introducing Polaris** - Unified and for the web. Release Candidate](https://shopify.dev/beta/next-gen-dev-platform/polaris)
[Skip to content](https://polaris-react.shopify.com/getting-started/designing-with-a-system#main)
[Polaris React](https://polaris-react.shopify.com/)
Search /
Building with Polaris
=====================

At Shopify, we often say, “Polaris is the floor, not the ceiling.” The design system provides you with building blocks, and it’s up to you to construct them in a way that best meets your user’s needs. The idea behind Polaris not being a ceiling is that you shouldn’t limit your ideas to fit into existing system pieces too early. Zoom out, figure out the best design solution to the problem, and then see if Polaris has all the pieces for you to design that solution. If there’s a gap, then [contribute](https://polaris.shopify.com/contributing)
to the system to make it better.
Zoom out
--------
No matter what problem you’re solving, zooming out allows you to get a better understanding of the problem, and its sphere of influence. A problem rarely exists in isolation, so understanding context and contributing factors is key before getting into solutions. Practically speaking, this means that you should understand the product as a whole, not just the product area you’re working on.
For instance, if you work on Orders, you should have a holistic understanding of the Shopify admin so you can leverage existing patterns and mental models. You can also gain context and empathy for merchants through research.
Merchants don’t care about Shopify’s internal organization. They use the admin as a whole, so we must design with the whole experience in mind.

The Deliver team identified a need to consolidate 6 different tag components with varying UX that were doing the same job in different sections of the admin. The redundancy in components was causing a fractured user experience.
Explore freely
--------------
When you understand the product as a whole, you should be well equipped to explore without constraints. That means don’t start from our UI kit, component library, or patterns you see in the product---start with a blank sheet of paper instead. Solve the problem, preferably in more than one way, before you start worrying about consistency.

As the Deliver team was working on consolidating the 6 components, they also identified an opportunity to improve the overall usability for adding tags. The team explored several different ideas and approaches to understand which approach would best solve the problem.
Calibrate
---------
Once you understand the problem and potential solutions, you can start aligning more closely with the design system.

The team made updates to the Polaris foundational pieces like the tag, icon, and interactions so that they could use those pieces to build a more opinionated component.
If you have initial questions about contribution, reach out in #polaris if you work at Shopify, or the Shopify Partners Slack if you’re an open source contributor. To get help with the strategy for a larger contribution, start a GitHub discussion with the system community.
On this page
------------
---
# Listbox — Shopify Polaris React
[**Introducing Polaris** - Unified and for the web. Release Candidate](https://shopify.dev/beta/next-gen-dev-platform/polaris)
[Skip to content](https://polaris-react.shopify.com/components/lists/listbox#main)
[Polaris React](https://polaris-react.shopify.com/)
Search /
Listbox
=======
A Listbox is a vertical list of interactive options, with room for icons, descriptions, and other elements.
### Listbox component examples
DefaultWith LoadingWith ActionWith custom elementWith search
Basic implementation of a control element used to let merchants select options
Edit in CodeSandbox
ReactHTML
import {Listbox} from '@shopify/polaris';
import React from 'react';
function BaseListboxExample() {
return (
Learn more about Fraud Protect.
Don't * Remove underlines when the user cannot determine it's interactivity Example Learn more about Fraud Protect. ### Submitting data Merchants generally expect links to navigate, and not to submit data or take action. If you need a component that doesn’t have a URL associated with it, then use the [button component](https://polaris.shopify.com/components/actions/button) instead. ### Labeling Give links text that clearly describes their purpose. The accessibilityLabel prop adds an aria-label attribute to the link, which can be accessed by assistive technologies like screen readers. Typically, this label text replaces the visible text on the link for merchants who use assistive technology. To provide consistency and clarity: * Use the same text for links that navigate to the same content * Use different text for links that navigate to different content Do Example fulfilling orders Don't Example fulfilling orders Do Example /* Somewhere in the code: */ fulfilling orders /* Elsewhere in the code: */ fulfilling orders Don't Example /* Somewhere in the code: */ fulfilling orders /* Elsewhere in the code: */ order fulfillment section ### Keyboard support Links use browser defaults for keyboard interaction. * Give links keyboard focus with the tab key (or shift + tab when tabbing backwards) * Activate links with the enter/return key On this page ------------ --- # Pagination — Shopify Polaris React [**Introducing Polaris** - Unified and for the web. Release Candidate](https://shopify.dev/beta/next-gen-dev-platform/polaris) [Skip to content](https://polaris-react.shopify.com/components/navigation/pagination#main) [Polaris React](https://polaris-react.shopify.com/) Search / 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. ### Pagination component examples DefaultWith keyboard navigationWith labelWith table type Use for pagination of resources. Edit in CodeSandbox ReactHTML import {Pagination} from '@shopify/polaris'; import React from 'react'; function PaginationExample() { return (Tab {selected} selected
Your mailing list lets you contact customers or visitors who have shown an interest in your store. Reach out to them with exclusive offers or updates about your products.
Test linkBy signing up for the Shopify service (“Service”) or any of the services of Shopify Inc. (“Shopify”) you are agreeing to be bound by the following terms and conditions (“Terms of Service”). The Services offered by Shopify under the Terms of Service include various products and services to help you create and manage a retail store, whether an online store (“Online Services”), a physical retail store (“POS Services”), or both. Any new features or tools which are added to the current Service shall be also subject to the Terms of Service. You can review the current version of the Terms of Service at any time at https://www.shopify.com/legal/terms. Shopify reserves the right to update and change the Terms of Service by posting updates and changes to the Shopify website. You are advised to check the Terms of Service from time to time for any updates or changes that may impact you.
View a summary of your online store’s performance.
Tab {selected} selected
Use Instagram posts to share your products with millions of people. Let shoppers buy from your store without leaving Instagram.
No sales channels selected
Shopify POS is the easiest way to sell your products in person. Available for iPad, iPhone, and Android.