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

# Migrate Positioned​Overlay from Polaris React

Choose `s-popover` for contextual content, `s-tooltip` for brief supplementary text, or `s-modal` for a dialog task. Let that component own positioning and focus.

***

## Choose the destination

| Polaris React | Polaris web components | Migration type |
| - | - | - |
| `PositionedOverlay` | `s-popover`, `s-tooltip`, or `s-modal` | Compose |

***

## Map positioned overlay responsibilities

| Polaris React responsibility | Polaris web components | Migration notes |
| - | - | - |
| Anchored action content | `s-popover` | Connect the trigger with `commandFor` and keep the popover as a sibling. |
| Descriptive hover or focus content | `s-tooltip` | Associate it with `interestFor` and don't put actions inside it. |
| Placement, collision, and `active` state | Destination overlay plus commands or methods | Remove manual rectangles and verify Escape, dismissal, and focus restoration. |

***

## Migrate the call site

1. Identify each responsibility currently hidden behind `PositionedOverlay`: layout, semantics, state, actions, and responsive behavior.

2. Build the documented composition for those responsibilities; don't create a compatibility wrapper that accepts the old API.

3. Reconnect app state and verify the composition at every existing call site.

4. After verification, remove the `PositionedOverlay` import and any Polaris-only state, wrappers, or helpers that no longer have a caller.

***

## Preserve these behaviors

* Information hierarchy, reading order, and accessible relationships.
* App-owned state and every action or navigation outcome.
* Responsive behavior and focus order across the composed elements.

***

## Test and remove Polaris React

Test the complete `PositionedOverlay` composition at each responsive size used by the app. Verify reading and focus order, accessible relationships, keyboard interaction, and every action outcome.

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.

***