Migrate Portals
Remove PortalsManager after all Polaris React overlays and portal consumers are gone. Test stacking, focus, and dismissal on each migrated overlay first.
Anchor to Choose the destinationChoose the destination
| Polaris React | Polaris web components | Migration type |
|---|---|---|
PortalsManager | Remove after migrating Polaris React overlays. | Remove |
Anchor to Remove provider responsibilitiesRemove provider responsibilities
| Polaris React responsibility | Polaris web components | Migration notes |
|---|---|---|
| Shared portal mount | Remove | Polaris web component overlays don't need a Polaris React portal host. |
| Modal and popover stacking | Managed by s-modal and s-popover | Don't recreate a z-index manager around migrated overlays. |
| Test wrapper | Remove from render helpers | Mock only the web components and App Bridge APIs that the test uses. |
Anchor to Migrate the call siteMigrate the call site
-
Find every
PortalsManagerconsumer and identify which behavior, if any, still depends on it. -
Migrate those dependent components or behaviors first.
-
Delete
PortalsManagerand its now-unused state or helper code once it has no remaining responsibility. -
Verify the containing workflow without the removed layer.
Anchor to Preserve these behaviorsPreserve these behaviors
- Any user-visible behavior that was coupled to the removed component.
- Behavior of remaining descendants, including focus, scrolling, overlays, or context where relevant.
- Test setup and cleanup paths that referenced the removed layer.
Anchor to Test and remove Polaris ReactTest and remove Polaris React
Test the workflows that formerly depended on PortalsManager. Verify remaining descendants render correctly and that focus, scrolling, overlays, and test setup no longer rely on the removed layer.
Don't remove @shopify/polaris while another component still imports it. Once all call sites are migrated, remove the package and its provider-level setup, then run the app's full test suite.