---
title: Migrate to the Polaris grid component
description: >-
  Learn how to migrate the Grid component to Polaris web components in checkout
  and customer account UI extensions.
source_url:
  html: 'https://shopify.dev/docs/apps/build/checkout/migrate-to-web-components/grid'
  md: >-
    https://shopify.dev/docs/apps/build/checkout/migrate-to-web-components/grid.md
---

# Migrate to the Polaris grid component

The Polaris grid component creates CSS Grid-based layouts with rows and columns. It replaces the previous [`Grid`](https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/ui-components/layout-and-structure/grid) component and is available as [`<s-grid>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/grid) in API versions 2025-10 and newer.

***

## Updated properties

The following properties are different in the Polaris grid component.

### columns

The previous `Grid` `columns` prop is now called [`gridTemplateColumns`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/grid#properties-propertydetail-gridtemplatecolumns). The value format changes from an array to a CSS grid template string.

| Previous pattern | New pattern | Migration notes |
| - | - | - |
| `columns={['auto', 'fill']}` | `gridTemplateColumns="auto 1fr"` | `'fill'` becomes `1fr`. |
| `columns={['fill', 'fill']}` | `gridTemplateColumns="1fr 1fr"` | Array items become space-separated values. |
| `columns={['fill', 'fill', 'fill']}` | `gridTemplateColumns="1fr 1fr 1fr"` | Same pattern for any number of columns. |

Because `gridTemplateColumns` accepts standard CSS grid syntax, you can now use `repeat()` and `minmax()` for more flexible layouts:

```tsx
<s-grid gridTemplateColumns="repeat(3, 1fr)">...</s-grid>


<s-grid gridTemplateColumns="minmax(100px, 1fr) 2fr">...</s-grid>
```

## Migrating columns to gridTemplateColumns

##### Latest (Preact)

```tsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  return (
    <s-grid gridTemplateColumns="auto 1fr">
      <s-text>Column 1</s-text>
      <s-text>Column 2</s-text>
    </s-grid>
  );
}
```

##### Pre-Polaris (2025-07)

```tsx
import {
  reactExtension,
  Grid,
  Text,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  return (
    <Grid columns={['auto', 'fill']}>
      <Text>Column 1</Text>
      <Text>Column 2</Text>
    </Grid>
  );
}
```

**Responsive values:**

If you used `Style.default().when()` to make this property responsive, container queries replace the `Style` helper. Wrap your content in `<s-query-container>` and use `@container` syntax in the property value. Learn more in [Migrate StyleHelper to container queries](https://shopify.dev/docs/apps/build/checkout/migrate-to-web-components/style-helper).

### rows

The previous `Grid` `rows` prop is now called [`gridTemplateRows`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/grid#properties-propertydetail-gridtemplaterows). The value format changes from an array to a CSS grid template string.

| Previous pattern | New pattern | Migration notes |
| - | - | - |
| `rows={['auto', 'auto', 'auto']}` | `gridTemplateRows="auto auto auto"` | Array items become space-separated values. |

### spacing

The previous `Grid` `spacing` prop has been split into [`gap`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/grid#properties-propertydetail-gap), [`columnGap`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/grid#properties-propertydetail-columngap), and [`rowGap`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/grid#properties-propertydetail-rowgap).

| Previous pattern | New pattern | Migration notes |
| - | - | - |
| `spacing="base"` | `gap="base"` | Single `spacing` value maps to `gap`. |
| `spacing={['base', 'loose']}` | `rowGap="base" columnGap="large-200"` | Use separate properties for different row and column gaps. |

## Migrating spacing to gap

##### Latest (Preact)

```tsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  return (
    <s-grid gridTemplateColumns="1fr 1fr" rowGap="base" columnGap="large-200">
      <s-text>Item 1</s-text>
      <s-text>Item 2</s-text>
      <s-text>Item 3</s-text>
      <s-text>Item 4</s-text>
    </s-grid>
  );
}
```

##### Pre-Polaris (2025-07)

```tsx
import {
  reactExtension,
  Grid,
  Text,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  return (
    <Grid columns={['fill', 'fill']} spacing={['base', 'loose']}>
      <Text>Item 1</Text>
      <Text>Item 2</Text>
      <Text>Item 3</Text>
      <Text>Item 4</Text>
    </Grid>
  );
}
```

### block​Alignment

The previous `Grid` `blockAlignment` prop is now called [`alignItems`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/grid#properties-propertydetail-alignitems).

| Previous pattern | New pattern | Migration notes |
| - | - | - |
| `blockAlignment="center"` | `alignItems="center"` | Use `alignItems` to align items within their grid areas. |

## Migrating blockAlignment to alignItems

##### Latest (Preact)

```tsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  return (
    <s-grid gridTemplateColumns="1fr 1fr" gridTemplateRows="200px" alignItems="center">
      <s-text>Centered vertically</s-text>
      <s-text>Centered vertically</s-text>
    </s-grid>
  );
}
```

##### Pre-Polaris (2025-07)

```tsx
import {
  reactExtension,
  Grid,
  Text,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  return (
    <Grid columns={['fill', 'fill']} rows={[200]} blockAlignment="center">
      <Text>Centered vertically</Text>
      <Text>Centered vertically</Text>
    </Grid>
  );
}
```

### inline​Alignment

The previous `Grid` `inlineAlignment` prop is now called [`justifyItems`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/grid#properties-propertydetail-justifyitems).

| Previous pattern | New pattern | Migration notes |
| - | - | - |
| `inlineAlignment="end"` | `justifyItems="end"` | Use `justifyItems` to align items within their grid areas. |

### border

The previous `Grid` `border` shorthand controlled border *style* (for example, `border="dotted"`). On `<s-grid>`, [`border`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/grid#properties-propertydetail-border) controls border *size* by default and accepts a token-based shorthand for size, color, and style:

| Pattern | Example | Description |
| - | - | - |
| `'{size}'` | `border="base"` | Border size only. |
| `'{size} {color}'` | `border="base base"` | Border size and color. |
| `'{size} {color} {style}'` | `border="base base dashed"` | Border size, color, and style. |

| Previous value | New value | Migration notes |
| - | - | - |
| `'base'` (single solid border) | `border="base"` | Renders a default-size border. |
| `'dotted'` | `border="base base dotted"` | Specify size and color before style. |
| `'dashed'` | `border="base base dashed"` | Specify size and color before style. |
| `'none'` | `border="none"` or omit | No border. |

### border​Width

The previous `Grid` `borderWidth` accepted `'base'`, `'medium'`, `'thick'`. The Polaris grid [`borderWidth`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/grid#properties-propertydetail-borderwidth) accepts a reduced keyword set: `'none'`, `'base'`, `'large'`, `'large-100'`, `'large-200'`.

| Previous value | New value | Migration notes |
| - | - | - |
| `'base'` | `'base'` | No change needed. |
| `'medium'` | `'large'` | `'medium'` is removed. |
| `'thick'` | `'large-200'` | `'thick'` is removed. |

### display

The previous `Grid` `display` values `'inline'` and `'block'` are no longer accepted. The Polaris grid [`display`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/grid#properties-propertydetail-display) accepts `'auto'` (the default) and `'none'`.

| Previous value | New value | Migration notes |
| - | - | - |
| `'block'` | `'auto'` (the default) | Omit `display` for default block-level rendering. |
| `'inline'` | Removed | Wrap inline content in [`<s-text>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/text) instead. This advice applies only when migrating `display="inline"` usages — direct text children of `<s-grid>` are still valid for non-inline content. |
| `'none'` | `'none'` | No change needed. |

### padding

The previous `Grid` `padding` prop's accepted values and multi-side shorthand format have changed.

Use the following mapping to migrate deprecated tokens:

| Previous | New |
| - | - |
| `'none'` | `'none'` |
| `'extraTight'` | `'small-400'` |
| `'tight'` | `'small-200'` |
| `'base'` | `'base'` |
| `'loose'` | `'large-200'` |
| `'extraLoose'` | `'large-500'` |

The new token scale also adds `'small-500'`, `'small-300'`, `'small-100'`, `'small'`, `'large'`, `'large-100'`, `'large-300'`, and `'large-400'`.

For more on the scale system, see [Scale](https://shopify.dev/docs/api/checkout-ui-extensions/latest/using-polaris-components#scale).

The multi-side shorthand format has also changed:

| Previous | New |
| - | - |
| Array of 2 or 4 values: `['base', 'none']` | Space-separated string with 1 to 4 values: `"base none"`. The 3-value variant `"block-start inline block-end"` is also supported. |

To set padding on a single side or axis, use [`paddingBlock`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/grid#properties-propertydetail-paddingblock) or [`paddingInline`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/grid#properties-propertydetail-paddinginline) instead of `padding`.

### accessibility​Role

Several `accessibilityRole` values have been renamed in the Polaris grid component. Update them to the new role names:

| Previous value | New value |
| - | - |
| `'complementary'` | `'aside'` |
| `'orderedList'` | `'ordered-list'` |
| `'unorderedList'` | `'unordered-list'` |
| `'listItem'` | `'list-item'` |

Other previously supported roles (`'main'`, `'header'`, `'footer'`, `'section'`, `'navigation'`, `'separator'`, `'status'`, `'alert'`) are accepted unchanged. The Polaris grid also adds the following new roles:

| New role | Description |
| - | - |
| `'list-item-separator'` | Separator between list items. |
| `'generic'` | Generic container. |
| `'presentation'` | Decorative element. |
| `'none'` | No semantic role. |

***

## New properties

The Polaris grid component introduces the following new properties:

| New prop | Type | Description |
| - | - | - |
| [`accessibilityVisibility`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/grid#properties-propertydetail-accessibilityvisibility) | `'visible'` \| `'hidden'` \| `'exclusive'` | Controls visibility for assistive technologies. |
| [`columnGap`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/grid#properties-propertydetail-columngap) | `string` | Controls horizontal spacing between grid items. |
| [`placeContent`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/grid#properties-propertydetail-placecontent) | `string` | Shorthand for setting both `alignContent` and `justifyContent`. |
| [`placeItems`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/grid#properties-propertydetail-placeitems) | `string` | Shorthand for setting both `alignItems` and `justifyItems`. |
| [`rowGap`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/grid#properties-propertydetail-rowgap) | `string` | Controls vertical spacing between grid items. |

***