Migrate Scroll
Remove ScrollLock when its owning Polaris overlay is migrated. Keep custom scroll locking only for custom overlays with complete focus and dismissal behavior.
Anchor to Choose the destinationChoose the destination
| Polaris React | Polaris web components | Migration type |
|---|---|---|
ScrollLock | Remove for Polaris overlays. Use a custom implementation only for custom overlays. | Remove |
Anchor to Map scroll-lock responsibilitiesMap scroll-lock responsibilities
| Polaris React usage | Polaris web components | Migration notes |
|---|---|---|
| Lock while a modal is open | s-modal | Remove the separate lock and verify that background content can't scroll or receive focus. |
| Lock while a popover is open | Usually remove | Popovers shouldn't normally freeze the page. |
active | Overlay visibility or command state | Keep one source of truth and restore scroll position when custom workflows close. |
Anchor to Migrate the call siteMigrate the call site
-
Find every
ScrollLockconsumer and identify which behavior, if any, still depends on it. -
Migrate those dependent components or behaviors first.
-
Delete
ScrollLockand 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 ScrollLock. 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.