Migrate to the Polaris grid component

The Polaris grid component creates CSS Grid-based layouts with rows and columns. It replaces the previous Grid component and is available as <s-grid> in API versions 2025-10 and newer.

Anchor to Updated propertiesUpdated properties

The following properties are different in the Polaris grid component.

Anchor to columnscolumns

The previous Grid columns prop is now called gridTemplateColumns. The value format changes from an array to a CSS grid template string.

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

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

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

Anchor to rowsrows

The previous Grid rows prop is now called gridTemplateRows. The value format changes from an array to a CSS grid template string.

Anchor to spacingspacing

The previous Grid spacing prop has been split into gap, columnGap, and rowGap.

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

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

Anchor to blockAlignmentblockAlignment

The previous Grid blockAlignment prop is now called alignItems.

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

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

Anchor to inlineAlignmentinlineAlignment

The previous Grid inlineAlignment prop is now called justifyItems.

Anchor to borderborder

The previous Grid border shorthand controlled border style (for example, border="dotted"). On <s-grid>, border controls border size by default and accepts a token-based shorthand for size, color, and style:

Anchor to borderWidthborderWidth

The previous Grid borderWidth accepted 'base', 'medium', 'thick'. The Polaris grid borderWidth accepts a reduced keyword set: 'none', 'base', 'large', 'large-100', 'large-200'.

Anchor to displaydisplay

The previous Grid display values 'inline' and 'block' are no longer accepted. The Polaris grid display accepts 'auto' (the default) and 'none'.

Anchor to paddingpadding

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

Use the following mapping to migrate deprecated tokens:

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.

The multi-side shorthand format has also changed:

To set padding on a single side or axis, use paddingBlock or paddingInline instead of padding.

Anchor to accessibilityRoleaccessibilityRole

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

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

Anchor to New propertiesNew properties

The Polaris grid component introduces the following new properties: