Migrate Positioned
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.
Anchor to Choose the destinationChoose the destination
| Polaris React | Polaris web components | Migration type |
|---|---|---|
PositionedOverlay | s-popover, s-tooltip, or s-modal | Compose |
Anchor to Map positioned overlay responsibilitiesMap 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. |
Anchor to Migrate the call siteMigrate the call site
-
Identify each responsibility currently hidden behind
PositionedOverlay: layout, semantics, state, actions, and responsive behavior. -
Build the documented composition for those responsibilities; don't create a compatibility wrapper that accepts the old API.
-
Reconnect app state and verify the composition at every existing call site.
-
After verification, remove the
PositionedOverlayimport and any Polaris-only state, wrappers, or helpers that no longer have a caller.
Anchor to Preserve these behaviorsPreserve 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.
Anchor to Test and remove Polaris ReactTest 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.