polaris

Summary: this is the first major version of Polaris React since launch. Included in this release are:

• Several new components, including data table, drop zone, app provider, and modal
• Improvements to existing components, such as resource list, choice list, and cards
• A few breaking API changes

Breaking changes

React 16+

We’re removing support for React 15 in order to make full use of some of the new features in React 16, such as fragments, error boundaries, and improved server-side rendering.

Upgrade instructions

Upgrade your app to the latest version of React.

App provider

The AppProvider component is now required in your app for Polaris components to function properly.

Upgrade instructions

Wrap your app in the AppProvider component.

Collapsible component requires an id prop

For accessibility reasons, the id prop is now required on the Collapsible component.

Upgrade instructions

Pass a unique value as an id to all <Collapsible> components. For example, <Collapsible id="my-unique-id">.

EmbeddedApp component has been removed

The EmbeddedApp component has been removed. The AppProvider component now accepts the configuration needed to initialize an embedded app.

Upgrade instructions

Use the AppProvider component with the apiKey and shopOrigin props.

Resource list

Shopify is organized around objects that represent a merchant’s business, such as customers, products, and orders. Each individual order, for example, is given a dedicated page that can be linked to. In Shopify, we call these types of objects resources.

The resource list component functions as:

• A content format, presenting a set of individual resources in a compact form
• A system for taking action on one or more individual resources
• A way to navigate to the show page of an individual resource

Our current resource list component gave you some nice defaults out of the box, but didn’t take you much further than that. We recognized that each of these lists is unique and contains different information that is important to the merchant.

Our new resource list allow you to build custom items in the list, with their own layout, content, and styling. This gives you a powerful way to build these sorts of lists going forward.

We’ve also included in depth documentation and a tutorial on how to build your own custom resource list items.

Tabs no longer accept title prop

To be more consistent with our other component APIs, the Tabs component now uses content instead of title.

Upgrade instructions

Change all instances of title to be content instead.

TextField onChange is required

Because we require you to manage state for your inputs, we decided to make onChange required for TextField to avoid confusion.

Upgrade instructions

Add an onChange callback to each use of TextField that is not disabled or readonly.

Removed default white color from Icon CSS

The CSS for Icons will no longer apply a color to icons by default. You must use the color prop on the Icon component to specify the color.

Upgrade instructions

Use color prop on all instances of Icon component.

Anchor tags are no longer styled by Polaris components

To avoid conflicts with other styling or frameworks, we’re removing the styling we globally applied to all a elements.

Upgrade instructions

Use the Link component instead.

Changed Alert onCancel prop to onClose

This change only impacts users of the Sass version of Polaris, more specifically the color() function. The color($hue, $value: base, $for-background: null) function in Sass now accepts strings for $hue and $value as advertised in the color function documentation.

Upgrade instructions

If you’re using VS Code, here are the exact search / replace instructions to follow (toggle “Use Regular Expression”):

• replace \bcolor\(([a-z-]+)\) with color('$1')
• replace \bcolor\(([a-z-]+), ([a-z-]+)\) with color('$1', '$2')
• replace \bcolor\(([a-z-]+), ([a-z-]+), (.*)\) with color('$1', '$2', $3)

New components

Data table

Since launching Polaris components, we’ve had many people ask why we didn’t include tables. While we have been moving away from using tables for comparisons that aren’t tabular data (resource lists, for example), we recognize that there are still cases to use them.

The data table component is our answer to those cases. While data visualizations represents part of a data set, data tables are used to organize and display all the information from a data set, allowing merchants view details from the entire set. This helps merchants compare and analyze all the data in a unified way.

Drop zone

Currently we have several different interfaces for uploading files across Shopify, which leads to a lack of consistency and some missing features and capabilities. To solve this problem, we’re releasing a new drop zone component.

This new component allows merchants to upload files by dragging and dropping them into an area on a page. The component handles file type validation, dropping onto the window, and more, meaning more ease of use for merchants.

Modal

In the original Polaris React, the modal component was only available to embedded apps. No longer. Our new modal component is universal in that it can be used in either standalone or embedded apps, and will handle the correct behavior for you.

App provider

The app provider is a required component that enables sharing global app config with the components in Polaris. This is used for the internationalization of strings in Polaris components, as well as set other configuration such as a custom link component that all the Polaris components will use. This unlocks new ways for us to share configuration at an app level and have the components react to that configuration.

Enhancements

• Added error prop to ChoiceList
• TextField, Select, and Checkbox now accept the types string or ReactElement for the error prop
• Added optional id props to more components, and restructured the prop definitions to allow projects to make id props mandatory
• Added fullWidth prop to Card.Section
• Added fullHeight prop to Popover to override max-height
• Added allowRange as a property for DatePicker
• Added the external option to the secondaryAction.action prop on the Banner component. Thank you to (Andrew Cargill) for the issue (#236)

Bug fixes

• Enforced subdued description text style in AnnotatedSection
• Fixed an overflow bug causing the border of TextField to be cut off
• Allowed specific props in the TextField component to pass through properties to the input child
• Fixed ActionList component to provide section dividers when a title was not provided
• Fixed an issue in the Select component where placeholder didn’t properly appear on Firefox and appeared disabled on all browsers

Bug fixes

• Fixed an issue in the select component where placeholder didn’t properly appear on Firefox and appeared disabled on all browsers
• Fixed missing dependency for lodash-decorators (thanks to @paul-phan for the original issue)

Various documentation improvements and fixes

Enhancements

• Upgrade to TypeScript 2.8.3
• Added disabled interactive state to the state mixin

This will be the last v1.x release outside of critical security fixes.

Bug fixes

• Add margin-left spacing to disclosure icon within Button component
• Remove margins on segmented ButtonGroup
• Fixed text alignment of link so that it inherits from its parent node

Breaking changes

• Moved persistActions from a prop on ResourceList to a prop on ResourceList.Item

Bug fixes

• Enforce subdued description text style in AnnotatedSection
• Fixed horizontal scrollbar and footer bottom alignment on Data Table
• Fixed Sass variable interpolation on ResourceList Item (thanks to @sdn90 for the original issue)
• Fixed data table sortable column heading alignment when content type is "text" (thanks @FelixTellmann for the original issue)

Bug fixes

• Fixing an error with the release process

Enhancements

• Changed term in DescriptionList component to accept React.ReactNode to allow for more than just string type

Embarrassingly enough, publishing v1.13.0 failed, meaning this shiny v1.13.1 patch also contains all changes from v1.13.0:

Enhancements

• Added an id prop to Collapsible to be referenced by the aria-controls attribute of the component triggering the collapse

Bug fixes

• Fixed external prop not working within ActionList component
• Fixed a syntax error in one of the Card component examples (thanks meecrobe for the original issue)

Chores

• Added missing publishConfig.access setting in package.json, in accordance with the new Shipit requirements for public npm packages

• Enhanced Avatar to work better when provided non-square images
• Move documentation file so it's picked up by the styleguide

Bug fixes

• Fixed disclosure centering on the tab component
• Fixed an issue where a style void would appear between breakpoints at high text zoom levels

Documentation

• Removed purpose section from component READMEs
• Added Embedded page under the Embedded section
• Added “Using embedded components” section
• Added screenshots to the embedded components
• Clarified usage of card header and footer actions

Documentation

• Moving property descriptions out of READMEs and into source files.

Bug fixes

• Fixed server-side environments

Documentation

• Updated component examples that use state to use an es6 class.

Bug fixes

• Fixed TextField overflow issues when inside Scrollable
• Fixed Select focus state bug occuring in Firefox
• Fixed vertical alignment of text within full width variant of the button component

Enhancements

• Changed Checkbox label to allow string or React.ReactNode
• Update TextField type with currency
• Added ariaControls, ariaExpanded prop to Button
• Updated the base red color to improve contrast
• Added a notification icon to the bundled icons available to use in the icon component's source prop
• Exposed Status from the Banner component

Chores

• Added version number to source

• Changed Action to Disableable Action in Card

Enhancements

• Added renderChildren prop to choice list component

Bug fixes

• Fixed an issue with footer help links not expanding to full-width on mobile devices
• Added breadcrumbs to SkeletonPage
• Added max-width and auto margin to EmptyState
• Fixed outline button disabled state styles
• Fixed Tag so the onRemove function is not imporperly called (thanks chaddjohnson for the original issue )
• Fixed border on inputs disabled state
• Fixed an issue in TextInput, when you increment or decrement with a float value, and the digits after the decimal point where wrong
• Added top alignment to FormLayout.Group #876

Documentation

• Fixed capitalization of prop names in Pagination component’s documentation (thanks donnguyen for the original issue)
• Exposed Option from the Select component

Bug fixes

• Fixed the public repository’s build (which was missing the new CircleCI configuration files)

Bug fixes

• Fixed CSS only checkbox (thanks daddy88 for the original issue)

• Restored the correct latest version to the CDN
• Fixed rgbToHsb function when red is the largest number and added tests (thanks emcmanus for the original issue)
• Fixed an issue where a hard-coded path would cause the build to fail on Windows (thanks to @Invader444 for the original issue and pull request)
• Added onClick to UnstyledLink

Documentation

• Amending changelog

• Added onActionAnyItem prop to action list and used to close page actionGroups on click or keypress of any item
• Added content prop to tabs and deprecated use of title
• Added text container component
• Added idForItem prop to resource list
• Added fullWidth prop to layout section
• Added indeterminate as option for checkbox checked prop value
• Added singleColumn prop to page
• Added focused prop to text field

Bug fixes

• Fixed positioned overlay not responding to scrollable container events
• Fixed first focusable item focus in popovers)
• Fixed typos in the select component documentation (thanks mattchidley for the original issue)

Bug fixes

• Moved react-transition-group from a dev dependency to a dependency