v4.0.0

Polaris React v4.0.0 is a major release that introduces breaking changes, primarily due to updates made to component internals. This builds a stronger foundation that ensures readiness for future React performance improvements.

This release doesn’t include any new components, but it does update some components to use React Hooks. It also deletes several deprecated features and removes dependencies on legacy context and unsafe lifecycle methods. Thanks to these improvements, Polaris React is React Strict Mode compliant.

For instructions on updating from v3 to v4, read the migration guide.

Breaking changes

• Removed groups prop on Select. Pass groups to the options prop instead. (#1831)
• Removed Autocomplete.ComboBox.TextField and Autocomplete.ComboBox.OptionList. You should use the Autocomplete.TextField and OptionList components instead. (#1830)
• Removed secondaryFooterAction prop on Card. Pass an array of secondary actions to the secondaryFooterActions prop instead. (#1831)
• Removed iconBody prop on Navigation.Item. Pass a string to the icon prop instead. (#1831)
• Removed the WithContext component, as it was an undocumented part of the public API meant for internal use only (#1641)
• Removed the WithRef component, as it was an undocumented part of the public API meant for internal use only (#1610)
• Removed support for passing a string into <Icon source> to load a bundled icon. You must load the required icon directly from @shopify/polaris-icons instead. (#1604)
• Removed support for passing an SvgSource shaped object into <Icon source> to load an icon imported using Shopify’s legacy icon loader. You must update sewing-kit to at least v0.82.0 which replaced the legacy loader with using SVGR. (#1604)
• Removed support for passing a React Element into <Icon source>. You must pass in a React Component that returns an SVG element instead. (#1604)
• Removed support for <Icon untrusted>. Passing a string into source will now always load an untrusted icon, you don't need that additional property. (#1604).
• Removed Navigation.UserMenu. Use TopBar.UserMenu instead. (#1599)
• Made title a required prop on ChoiceList to improve accessibility. It can be hidden with titleHidden. (#1575)
• Made i18n a required prop on AppProvider. Usage instructions are included in the AppProvider docs. (#1530)
• Upgraded react and react-dom peer-dependencies to 16.8.6 to enable the use of hooks (#1525)
• Changed the import method for React to use default imports. Applications consuming Polaris using TypeScript must enable esModuleInterop in tsconfig.json. (#1523)
• Removed LinkLikeComponent type export. Use AppProviderProps['linkComponent'] instead. (#1864)
• Removed the Modal.Dialog and Tabs.Panel subcomponents as they were undocumented parts of our public API meant for internal use only (#1899).

Enhancements

• Added a new create-react-app example in TypeScript demonstrating use of Polaris with react-testing (#1937)
• Exported AppliedFilterInterface and FilterInterface from Filters (#1924)
• Improved color contrast of links inside Banner (#1651)
• Add underline to Links and Plain button on hover, so it doesn't rely on color alone for accessibility (#1885)
• Add onQueryFocus callback prop to the Filters component (#1948)

Bug fixes

• Fixed types merge of ActionMenu MenuAction and MenuGroup.actions (#1895)
• Fixed the activator buttons of Page actionGroups not toggling the Popover active state on click #1905
• Fixed Windows high contrast support of Badge progress (#1928)
• Fixed BulkActionButton from throwing an error in componentDidMount (#1913)
• Fixed ToastManager from not working correctly in React.StrictMode (#1741)
• Updated translation.yml with the new locales path (#1649)
• Fixed accessibility issue with Tabs list item presentation role (#1958)
• Fixed cross-origin error being thrown in Modal when loading an external app (#1992)
• Fixed regression in PopoverOverlay causing onClose to be fired when Popover is opening and trigger was not the activator (#2000)
• Fixed issue with ContextualSaveBar blocking search when hidden (#2044)

Documentation

• Updated AppProvider app bridge example to use our AppBridgeContext (#1877)

Development workflow

• Added support for React hooks in Storybook (#1665)
• Created toBeDisabled, mountWithContext and added custom testing matchers (#1596)
• Added PolarisTestProvider helper to ease configuration of required Polaris contexts in tests, see polaris examples for usage (#1810)
• Enabled strict mode in TypeScript (#1883)
• Moved to unpkg.com for our CDN CSS assets, instead of using sdks.shopifycdn.com. Existing URLs will continue to work but new versions will only be available at unpkg.com. (#1960)
• Added ChromaUI integration for previewing Storybook builds, to potentially replace our self-hosted Heroku instance (#1975)

Dependency upgrades

• Updated @shopify/polaris in all examples to 4.0.0-rc.2 (#1937)
• Added @material-ui/react-transition-group and removed react-transition-group to support React.StrictMode (#1759)
• Added @shopify/react-testing (#1596)
• Removed@shopify/css-utilities (#1586)
• Removed @types/prop-types and prop-types (#1505)
• Updatedreact to 16.8.6 and enzyme to 3.9.1 (#1392)

Code quality

• Bumped test coverage in Collapsible (#1929)
• Bumped test coverage in DropZone, Frame, Icon, and Loading (#1927)
• Removed unused type definitions (#1862)
• Ignored deprecation warnings related to Shopify App Bridge in tests (#1852)
• Updated withAppProvider to use a functional component rather than a class component (#1813)
• Updated Link to use useI18n rather than withAppProvider (#1806)
• Updated several components to use hooks instead of withAppProvider (#1797)
• Removed CSSTransition from PopoverOverlay (#1756)
• Updated exports in src/utilities and src/test-utilities to named exports (#1717)
• Removed test errors and non-deprecation warnings (#1715)
• Enabled React.StrictMode in test components and Storybook (#1709)
• Removed all uses of ReactDOM.findDOMNode (#1696)
• Enabled react/no-unsafe ESLint rule with checkAliases ([#169...

v3.21.1

Enhancements

• Added onQueryFocus callback prop to the Filters component (#1948)

v3.21.0

Enhancements

• Added a subtitle and thumbnail prop to Page (#1880)

Bug fixes

• Fixed accessibility issue with ChoiceList errors not being correctly connected to the inputs (#1824)
• Fixed Tab aria-controls pointing to a non-existent Panel id (#1869)
• Fixed Toast accessibility issue by moving aria-live prop to ToastManager (#1873)

Code quality

• Use @shopify/typescript-configs as the base of tsconfig.json for the project (#1829)

v3.20.0

Enhancements

• Added a verticalAlign prop to DataTable (#1790)
• Improved focus and hover states for Navigation (#1822)

Bug fixes

• Fixed the SearchInput clear button which was overflowing the search bar in Firefox 65+ (#1795)
• Fixed a bug preventing the display of Tooltip when cursor enters from a disabled element (#1783)
• Fixed React imports in the Filters component to use import * as React for projects that don't use esModuleInterop (#1820)
• Fixed tabIndex on main element causing event delegation issues (#1821)
• Fixed icon color for destructive ActionList items (#1836)
• Fixed not being able to explictly set autoComplete prop onAutocomplete.TextField (#1839)

Documentation

• Added links to App Bridge React component documentation in deprecation notices for embedded components (#1765)
• Improved link text for App Bridge deprecation notices #1802

Development workflow

• Use explicit imports for our base sass mixins instead of having them implicitly defined at build-time. This simplifies our build config and other tooling that wants to build us from source [#1680]

v3.19.0

New components

• Filters: Use to filter the items of a list or table (#1718)

Enhancements

• Added the rollover and Windows high contrast mode to Disclosure button on Tabs (#1755)
• Added support for disabling all choices in ChoiceList (#1758)
• Components in our sass build (the styles folder) are now precompiled to avoid the chance of accidentally overwriting any of our global variables, mixins and functions (#1764)
• Changed Skip to content to render an anchor instead of a button to meet accessibility level A guidelines (#1785)

Bug fixes

• Fixed a regression introduced in #1247, where icons inside of Link would always be recolored to match the text color (#1729)
• Fixed the DiscardConfirmationModal not closing when the discard button is clicked (#1784)
• Fixed Navigation.Item secondaryAction wrapping when content wraps (#1678)

Documentation

• Added links to App Bridge React component documentation in deprecation notices for embedded components (#1765)

Development workflow

• Renamed yarn run ts to yarn run type-check to match most other Shopify projects (#1745)
• Fixed deprecation notice in build (#1754)
• Simplified our rollup plugin for sass compilation while retaining identical behaviour (#1753)

v3.18.0

New components

• ActionMenu: Use for display of actions and action groups within the context of a header (#1653)

Enhancements

• Added the stopAnnouncements prop to Banner, which disables screen reader announcements when content changes (#1719)
• Add selectable prop to ResourceList component (thanks to @vict-shevchenko for the pull request)
• Allow Link and Button interactions when rendered as prefix/suffix within <TextField /> (#1394)
• Improve TextField so that character count is only announced on focus. (#1720)
• ActionList can now pass a unique accessibilityLabel to each Item (#1653)
• Greatly reduced complexity of Page > Header (#1653)
• Long Page > Header breadcrumb labels will now truncate instead of breaking layout (#1653)
• Improves performance of TabMeasure component (#1544)
• Added secondaryFooterActions prop to Card which adds an action list of secondary actions to the footer #1625

Bug fixes

• Fixes monochrome variant of Link and Button components to support multi-line link text (#1686)
• Fixed the first column of DataTable not rendering in iOS Safari (#1605)
• Fixed paint loss on scroll of TextField Spinner (#1740)

Documentation

• Mentioned that the Contextual Save Bar is now available for embedded apps through App Bridge directly #1721
• Mentioned Polaris icons in the Icon component documentation (#1693)
• Added an example to Card for custom action layout with a secondary action and a plain button (thanks to @sharoonthomas for the pull request)

Development workflow

• Updated Storybook to v5.1.9 (#1728)

Code quality

• Updated PositionedOverlay to no longer use componentWillReceiveProps(#1621)

Deprecations

• Card secondaryFooterAction is now deprecated. Set an array of secondary actions on the secondaryFooterActions prop instead #1625

v3.17.0

Deprecations

• Deprecated passing a string representing a "bundled icon" into <Icon source> Pass in an svg component imported from @shopify/polaris-icons instead (#1534).
• Deprecated all usage of the Shopify App Bridge in Polaris React (#1573)

Enhancements

• Made the action prop optional on EmptyState (#1583)
• Prevented Firefox from showing an extra dotted border on focused buttons (#1409)
• Added resolveItemId prop to ResourceList which is used in the new multiselect feature (#1261)
• Added actions prop to <Card.Section> to allow you to easily define header actions in a card section (#1598)
• Added <Card.Subsection> to allow you to further subdivide <Card.Section> in a consistent manner (#1611)
• Removed transition on tag button hover state #1337
• Added textAlign prop to Button (#1576)
• Made Button red when given both the plain and destructive props (#1603)
• Added support for disabled, destructive, and loading actions in Card and Card.Section (#1622)

Bug fixes

• Removed unnecessary border-radius from Modal body (#1584)
• Fixed accessibility issues in DropZone, Form, Modal, Section, Page, Tabs, TextField and TopBar (#1565,#1582).
• Fixed inconsistent width depending on your browser/version in Sheet (#1569)
• Fixed text and other elements from being selected in Safari when dragging the color picker (#1562)
• Fixed Banner title overflowing when set to a single long word (#1553)
• Remove export of CombinedProps and unneccessary export for Class based components (#1592)
• Fixed improper spacing and coloring on a TextField prefix (#1132)
• Fixed ResourcePicker not updating function references for onSelection and onCancel callbacks #1451
• Fixed TextField label being set as the value of the label node, as well as the aria-label aria-labelledby attributes, when only one method will suffice (#1615)
• Fixed accessibility issues for Windows High Contrast mode on Tabs and Popover (#1629)

Documentation

• Updated icon documentation to use imports from polaris-icons (#1561)
• Fixed an accessibility issue in the Collapsible component example (#1591)
• Added accessibility documentation for the RangeSlider component (#1630)
• Added accessibility documentation for the Collapsible component (#1631)
• Added accessibility documentation for the DescriptionList component (#1634)
• Added accessibility documentation for the Form component (#1636)
• Added accessibility documentation for the ExceptionList component (#1635)
• Added accessibility documentation for the KeyboardKey component (#1640)
• Added accessibility documentation for the Tag component (#1647)
• Added accessibility documentation for the Modal component (#1648)

Development workflow

• Made the a11y test that runs in CI fail if it finds any issues (#1564)
• Updated Storybook to v5.1.0-rc.4 (#1616)
• Fixed a visual regression testing issue with the Card component (#1618)
• Updated to sewing-kit v0.85.5 (#1633)

Dependency upgrades

• Upgraded TypeScript dependency to 3.5.1 (#1650)

Code quality

• Enabled the color contrast test in pa11y (#1645)
• Combined jsdocs in Icon for the untrusted prop (#1607)

v3.16.0

Enhancements

• Added support for dual values to RangeSlider component (#1436)
• Updated type restrictions for AnnotatedSection to allow its title prop to accept React.ReactNode instead of string (#1431)

Bug fixes

• Fixed an issue where the JavaScript breakpoints incorrectly set the navigation bar collapsed breakpoint (#1475)
• Added a border to Toast messages to make them more visible in Windows high contrast mode (#1469)
• Added box-shadow to the Banner to make it more visible in Windows high contrast mode (#1481)
• Added box-shadow to the Card to make it more visible in Windows high contrast mode (#1524)
• Fixed UI regressions in Navigation component hover and active states (#1551)

Development workflow

• Updated Storybook to v5.1.0-alpha.39, improving component search-ability in the sidebar (#1488)

Dependency upgrades

• Removed runtime dependency on @shopify/images as we never needed it at runtime (#1474)
• Removed @shopify/react-utilities and replaced some of the functionality with @shopify/css-utilities or by moving the utilities into Polaris itself (#1473)

v3.15.0

This release fixes an issue introduced in v3.14.0 that caused the esnext build not to succeed resulting in build errors for consumers (#1466)

Enhancements

• Enhanced NavigationItem's color accessibility for active, focus, hover and Selected states (1304)
• Added align prop to TextField (#1428)
• Added clearButton prop to TextField (#1226)

Bug fixes

• Fixed Checkbox from improperly toggling when disabled (#1467)
• Fixed Popover fade-in flutter on iOS by switching Transition component for CSSTransition (#1400)
• Improved the visibility of focus styles for the Link component. (#1425)

Documentation

• Updated accessibility testing documentation (#1449)
• Added guidelines for tertiary actions in modals to Modal component documentation (#1336)

Development workflow

• Updated the a11y shitlist and re-enabled the pa11y job in CI. The job always passes for now, as a way for us to judge whether it is stable and can be made a required check. (#1456)

Code quality

• Simplified logic in Checkbox component (#1453)

v3.14.0

⚠️ This release contains an issue that caused the esnext build to fail, resulting in errors for consumers of this particular bundle (fixed in 3.15.0).

---

New components

• Added the Sheetcomponent (#1250)

Enhancements

• Added translations for all supported locales (#1358)
• Improved the performance of ResourceList (#1313)
• Added withinContentContainer context to Navigation (#1393)
• Added support forTooltip content to wrap nonbreaking strings #1395

Bug fixes

• Removed window call on server executed code #1427
• Fixed onClick from firing three times when using the enter key on a ResourceList item (#1188)
• Resolved console [Intervention] errors for touch interactions on ColorPicker (#1414)
• Fixed page scrolling while interacting with the color slider (#1414)
• Applied font-family to button elements which were being overridden by User Agent Stylesheet (#1397)
• Fixed Checkbox being toggled when disabled (#1369)
• Fixed DropZone.FileUpload from incorrectly displaying action hint and title when the default is used and removed (#1233)
• Fixed ResourceList.Item interaction states from being incorrectly applied (#1312
• Fixed selected state for date picker in Windows high contrast mode (#1342)
• Fixed accessibility of skeleton components for Windows high contrast mode (#1341)
• Fixed Loading visibility in Windows high contrast mode (#1389)
• Fixed the position calculation of the PositionedOverlay component after scroll (#1382)
• Fixed styling issue for Pagination when used with Tooltip (#1277)
• Fixed certain children of a TextContainer having no top margin (#1357)
• Added border to Tooltip in Windows high contrast mode (#1405)
• Fixed Navigation.Section rollup collapsing when Navigation.Item subNavigationItems expand (#1417)

Documentation

• Updated Link accessibility documentation for the external prop to reflect new behavior (#1347)
• Added accessibility documentation for VisuallyHidden (#1348)
• Added accessibility documentation for TextStyle (#1350)
• Added accessibility guidance for Heading and Subheading (#1351)
• Added accessibility documentation for List and Stack (#1353)
• Added accessibility guidance for DisplayText (#1354)
• Added guidance for updating component documentation and tophatting style guide changes (#1362)
• Added accessibility documentation and guidance for ActionList and OptionList (#1365)
• Added accessibility documentation for Card and CalloutCard (#1366)
• Added accessibility documentation for Badge (#1364)
• Added accessibility documentation for Icon (#1404)
• Added accessibility documentation for Popover (#1408)
• Fixed content example for ContextualSaveBar guidelines (#1423)

Dependency upgrades

• Updated most devDependencies (#1327)
• Bumped @shopify/react-utilites to remove a transitive dependency on core-js (#1343)
• Updated App Bridge to version 1.3.0 (#1349)
• Updated typescript to 3.2.4 (#1388)
• Updated sewing-kit to 0.83.1 and babel-preset-shopify to ^18.1.0 (#1344)

Code quality

• Updated Dropzone.FileUpload to no longer use componentWillReceiveProps and componentWillMount (#1233)
• Removed a window.open implementation error in ResourceList.Item (#1294)