Migrate BlockLayout to the Polaris grid component

The previous BlockLayout component has been replaced by the <s-grid> component. Use gridTemplateRows to define the row tracks for your block layout. <s-grid> is available in API versions 2025-10 and newer.

Anchor to Updated propertiesUpdated properties

The following properties are different in the Polaris grid component.

Anchor to rowsrows

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

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

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

function Extension() {
  return (
    <s-grid gridTemplateRows="auto 1fr" gap="base">
      <s-text>Header</s-text>
      <s-text>Content that fills remaining space</s-text>
    </s-grid>
  );
}

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

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

function Extension() {
  return (
    <BlockLayout rows={['auto', 'fill']} spacing="base">
      <Text>Header</Text>
      <Text>Content that fills remaining space</Text>
    </BlockLayout>
  );
}

Anchor to spacingspacing

The previous BlockLayout spacing prop is now called gap.

Anchor to blockAlignmentblockAlignment

The previous BlockLayout blockAlignment prop is now called alignItems.

Anchor to inlineAlignmentinlineAlignment

The previous BlockLayout inlineAlignment prop is now called justifyItems.

Anchor to borderborder

The previous BlockLayout 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 BlockLayout 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 BlockLayout display values 'inline' and 'block' are no longer accepted. The Polaris grid display accepts 'auto' (the default) and 'none'.

Anchor to paddingpadding

The previous BlockLayout 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: