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 (#1695)
• Alphabetized component export order and kebab-case files (#1674)
• Updated Collapsible to no longer use componentWillReceiveProps(#1670)
• Restructured context structure to be more modular (#1664)
• Updated PositionedOverlay to no longer use componentWillReceiveProps(#1621)
• Simplified WithinContentContainer context type (#1602)
• Updated OptionList to no longer use componentWillReceiveProps (#1557)
• Refactored RangeSlider DualThumb tests (#1548)
• Converted Sheet to a functional component (#1548)
• Removed withContext from ResourceList.Item (#1503)
• Removed withContext from Navigation.Item (#1502)
• Removed withRef from UnstyledLink (#1501)
• Removed withContext from ResourceList.FilterControl (#1500)
• Removed withContext from Scrollable.ScrollTo and added a test to boost coverage (#1499)
• Removed withContext from Loading (#1497)
• Removed withContext and withAppProvider from ContextualSaveBar (#1498)
• Removed withContext from Toast (#1494)
• Removed withRef and withContext from DropZone.FileUpload (#1491)
• Created useAppBridge hook (#1482)
• Removed testID warning in tests (#1447)
• Updated AppProvider to use the new context API and refactored other instances to follow a new pattern and refactor test utilities (#1424)
• Updated all context files to export react context rather than a provider and consumer (#1424)
• Deleted withSticky (#1424)
• Upgraded the Autocomplete component from legacy context API to use createContext (#1403)
• Upgraded the Navigation component from legacy context API to use createContext (#1402)
• Updated ThemeProvider to use the new context API (#1396)
• Updated AppProvider to no longer use componentWillReceiveProps(#1255)
• Removed unused context from Scrollable (#1253)
• Updated ThemeProvider to no longer use componentWillReceiveProps (#1254)
• Removed context from Collapsible (#1114)
• Refactored Frame and its subcomponents to use the createContext API instead of legacy context (#803)
• Upgraded the Banner, Card, and Modal components from legacy context API to use createContext (#786)

Deprecations

• Renamed singleColumnonPagetonarrowWidth (#1606)