---
title: Migrate PortalsManager from Polaris React
description: Learn how to migrate Polaris React PortalsManager to Polaris web components.
source_url:
  html: >-
    https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react/portals-manager
  md: >-
    https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react/portals-manager.md
api_name: app-home
---

# Migrate Portals​Manager from Polaris React

Remove `PortalsManager` after all Polaris React overlays and portal consumers are gone. Test stacking, focus, and dismissal on each migrated overlay first.

***

## Choose the destination

| Polaris React | Polaris web components | Migration type |
| - | - | - |
| `PortalsManager` | Remove after migrating Polaris React overlays. | Remove |

***

## Remove 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. |

***

## Migrate the call site

1. Find every `PortalsManager` consumer and identify which behavior, if any, still depends on it.

2. Migrate those dependent components or behaviors first.

3. Delete `PortalsManager` and its now-unused state or helper code once it has no remaining responsibility.

4. Verify the containing workflow without the removed layer.

***

## Preserve 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.

***

## Test 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.

***