Migrate Scrollable from Polaris React
Use a native overflow container only where a bounded scrolling region is necessary. Preserve keyboard reachability and avoid nested scroll regions that trap navigation.
Anchor to Choose the destinationChoose the destination
| Polaris React | Polaris web components | Migration type |
|---|---|---|
Scrollable | Native scrolling container and app-owned CSS | Native HTML |
Anchor to Map scrollable behaviorMap scrollable behavior
| Polaris React | Polaris web components | Migration notes |
|---|---|---|
| Ordinary page content | Document flow | Remove the nested scroll region and let the embedded page scroll. |
| Constrained data or log region | Native element with overflow: auto and a defined size | Give the region an accessible name when users navigate it directly. |
shadow, focusable, and scroll callbacks | App-owned styling, native focus, and the scroll event | Verify keyboard order, cleanup, and that the shadow isn't the only overflow cue. |
Anchor to Migrate the call siteMigrate the call site
-
Choose the native element whose semantics match the
Scrollablecall site. -
Rebuild its accessible name and relationships before adding layout or app-owned styling.
-
When the element is interactive or form-associated, connect its native events and form behavior to existing app state.
-
After verification, remove the
Scrollableimport and any Polaris-only state, wrappers, or helpers that no longer have a caller.
Anchor to Preserve these behaviorsPreserve these behaviors
- Native semantics, accessible names, and document structure.
- Keyboard and form behavior supplied by the browser, where applicable.
- App state, validation, and responsive layout around the element.
Anchor to Test and remove Polaris ReactTest and remove Polaris React
Test the migrated Scrollable with browser and accessibility semantics in mind. Verify document structure, keyboard and form behavior where applicable, accessible relationships, and app-owned state changes.
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.