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 component and is available as <s-grid-item> in API versions 2025-10 and newer.

Anchor to Updated propertiesUpdated properties

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

Anchor to columnSpancolumnSpan

The previous GridItem columnSpan prop is now called gridColumn. The value format changes from a number to a CSS grid span string.

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>
  );
}

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>
  );
}

Anchor to rowSpanrowSpan

The previous GridItem rowSpan prop is now called gridRow. The value format changes from a number to a CSS grid span string.

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>
  );
}

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>
  );
}

Anchor to New propertiesNew properties

The Polaris grid item component introduces the following new properties: