---
title: Migrate Grid from Polaris React
description: >-
  Replace Polaris React Grid and Grid.Cell with s-grid and s-grid-item using
  explicit tracks and spans.
source_url:
  html: 'https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react/grid'
  md: >-
    https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react/grid.md
api_name: app-home
---

# Migrate Grid from Polaris React

Replace Polaris React `Grid` with [`s-grid`](https://shopify.dev/docs/api/app-home/web-components/layout-and-structure/grid) and `Grid.Cell` with `s-grid-item`. Use a stack when children only need sequential flow.

***

## Migrate columns and spans

## Migrating a grid with column spans

##### Polaris web components

```tsx
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

```tsx
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>
```

***

## Replace 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](https://shopify.dev/docs/api/polaris/using-polaris-web-components#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.

***

## Test 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.

***

## Remove 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.

***

## Related guidance

* [Grid component](https://shopify.dev/docs/api/app-home/web-components/layout-and-structure/grid)
* [Responsive values](https://shopify.dev/docs/api/polaris/using-polaris-web-components#responsive-values)
* [Migrate InlineGrid from Polaris React](https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react/inline-grid)
* [Migrate InlineStack from Polaris React](https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react/inline-stack)

***