Migrate Grid from Polaris React

Replace Polaris React Grid with s-grid and Grid.Cell with s-grid-item. Use a stack when children only need sequential flow.

Anchor to Migrate columns and spansMigrate columns and spans

Migrating a grid with column spans

function ContentGrid() {

return (

<s-grid gridTemplateColumns="repeat(12, minmax(0, 1fr))" gap="large">

<s-grid-item gridColumn="span 8">Main content</s-grid-item>

<s-grid-item gridColumn="span 4">Aside</s-grid-item>

</s-grid>

);

}

import {Grid} from '@shopify/polaris';

<Grid.Cell columnSpan={{xs: 1, sm: 2, md: 8}}>Main content</Grid.Cell>

<Grid.Cell columnSpan={{xs: 1, sm: 2, md: 4}}>Aside</Grid.Cell>

</Grid>

Polaris web components

function ContentGrid() {
  return (
    <s-grid gridTemplateColumns="repeat(12, minmax(0, 1fr))" gap="large">
      <s-grid-item gridColumn="span 8">Main content</s-grid-item>
      <s-grid-item gridColumn="span 4">Aside</s-grid-item>
    </s-grid>
  );
}

Polaris React

import {Grid} from '@shopify/polaris';

<Grid columns={{xs: 1, sm: 4, md: 12}} gap={{xs: '4', sm: '5'}}>
  <Grid.Cell columnSpan={{xs: 1, sm: 2, md: 8}}>Main content</Grid.Cell>
  <Grid.Cell columnSpan={{xs: 1, sm: 2, md: 4}}>Aside</Grid.Cell>
</Grid>

Preview

Anchor to Replace Grid propertiesReplace Grid properties

Polaris React	Polaris web components	Migration notes
`columns`	`gridTemplateColumns`	Use CSS grid tracks such as `repeat(12, 1fr)`.
Responsive column objects	Container-query value in `gridTemplateColumns`	Respond to embedded container width, not the browser viewport.
`gap`	`gap`, `rowGap`, or `columnGap`	Choose documented spacing keywords.
`areas`	No direct property	Remove named areas. Define tracks with `gridTemplateColumns` and `gridTemplateRows`, then place `s-grid-item` children with `gridColumn` and `gridRow`.
`Grid.Cell`	`s-grid-item`	Omit it when a direct child doesn't need placement.
`columnSpan`	`gridColumn`, such as `span 8`	Recalculate spans against the new track count.
`rowSpan`	`gridRow`	Avoid spans that create confusing reading order.

The example translates the medium-width 8/4 split directly. gridColumn accepts a static span N value, not a responsive string. When the old span changes by breakpoint, simplify the narrow layout to sequential flow or use separate responsive grid compositions instead of creating implicit columns. Use s-query-container when supported grid properties such as gridTemplateColumns use container queries. Never use visual grid placement to reverse keyboard or screen-reader order.

See responsive values for the container-query string syntax used by gridTemplateColumns, gap, and gridColumn.

s-grid doesn't expose gridTemplateAreas. If the old grid uses named areas, translate each area's placement into gridColumn and gridRow spans on s-grid-item. Keep the DOM in logical reading order, and use placement only to change the visual layout.

Anchor to Test the migrationTest the migration

Test every container threshold, not only viewport presets.
Verify long labels, translated content, validation errors, and zoom don't overlap.
Check DOM, reading, and focus order with layout styles removed.
Compare spans for missing, optional, and dynamically added content.

Anchor to Remove Polaris ReactRemove Polaris React

Remove Grid, Grid.Cell, breakpoint helpers, and span adapters after every layout is migrated. Remove @shopify/polaris only after no other route in scope imports it.

Anchor to Related guidanceRelated guidance

Was this page helpful?