---
title: Migrate to the Polaris grid item component
description: >-
  Learn how to migrate the GridItem 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-item
  md: >-
    https://shopify.dev/docs/apps/build/checkout/migrate-to-web-components/grid-item.md
---

# Migrate to the Polaris grid item component

The Polaris grid item component controls how a child spans columns and rows within a grid layout. It replaces the previous [`GridItem`](https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/ui-components/layout-and-structure/griditem) component and is available as [`<s-grid-item>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/grid#grid%20item) in API versions 2025-10 and newer.

***

## Updated properties

The following properties are different in the Polaris grid item component.

### column​Span

The previous `GridItem` `columnSpan` prop is now called [`gridColumn`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/grid#griditem-propertydetail-gridcolumn). The value format changes from a number to a CSS grid span string.

| Previous pattern | New pattern | Migration notes |
| - | - | - |
| `columnSpan={2}` | `gridColumn="span 2"` | Number values must be specified as `"span N"` strings. |
| Not specified | `gridColumn="auto"` | Default behavior is `"auto"` in both versions. |

## Migrating columnSpan to gridColumn

##### 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 1fr">
      <s-grid-item gridColumn="span 2">
        <s-text>Spans 2 columns</s-text>
      </s-grid-item>
      <s-text>Regular item</s-text>
    </s-grid>
  );
}
```

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

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

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

function Extension() {
  return (
    <Grid columns={['fill', 'fill', 'fill']}>
      <GridItem columnSpan={2}>
        <Text>Spans 2 columns</Text>
      </GridItem>
      <Text>Regular item</Text>
    </Grid>
  );
}
```

### row​Span

The previous `GridItem` `rowSpan` prop is now called [`gridRow`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/grid#griditem-propertydetail-gridrow). The value format changes from a number to a CSS grid span string.

| Previous pattern | New pattern | Migration notes |
| - | - | - |
| `rowSpan={3}` | `gridRow="span 3"` | Number values must be specified as `"span N"` strings. |
| Not specified | `gridRow="auto"` | Default behavior is `"auto"` in both versions. |

## Migrating rowSpan to gridRow

##### 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="auto auto auto">
      <s-grid-item gridRow="span 2">
        <s-text>Spans 2 rows</s-text>
      </s-grid-item>
      <s-text>Row 1</s-text>
      <s-text>Row 2</s-text>
    </s-grid>
  );
}
```

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

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

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

function Extension() {
  return (
    <Grid columns={['fill', 'fill']} rows={['auto', 'auto', 'auto']}>
      <GridItem rowSpan={2}>
        <Text>Spans 2 rows</Text>
      </GridItem>
      <Text>Row 1</Text>
      <Text>Row 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).

***

## New properties

The Polaris grid item component introduces the following new properties:

| New prop | Type | Description |
| - | - | - |
| [`accessibilityLabel`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/grid#griditem-propertydetail-accessibilitylabel) | `string` | Label for assistive technologies. |
| [`accessibilityVisibility`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/grid#griditem-propertydetail-accessibilityvisibility) | `'visible'` \| `'hidden'` \| `'exclusive'` | Controls visibility for assistive technologies. |

***