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

# Migrate BlockLayout to the Polaris grid component

The previous [`BlockLayout`](https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/ui-components/layout-and-structure/blocklayout) component has been replaced by the [`<s-grid>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/grid) component. Use [`gridTemplateRows`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/grid#properties-propertydetail-gridtemplaterows) to define the row tracks for your block layout. `<s-grid>` is available in API versions 2025-10 and newer.

***

## Updated properties

The following properties are different in the Polaris grid component.

### rows

The previous `BlockLayout` `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', 'fill']}` | `gridTemplateRows="auto 1fr"` | `'fill'` becomes `1fr`. |
| `rows={['auto', 'auto', 'auto']}` | `gridTemplateRows="auto auto auto"` | Array items become space-separated values. |

## Migrating BlockLayout to grid

##### 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 gridTemplateRows="auto 1fr" gap="base">
      <s-text>Header</s-text>
      <s-text>Content that fills remaining space</s-text>
    </s-grid>
  );
}
```

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

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

**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).

### spacing

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

| Previous pattern | New pattern | Migration notes |
| - | - | - |
| `spacing="base"` | `gap="base"` | Direct rename. |

### block​Alignment

The previous `BlockLayout` `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 along the block axis. |

### inline​Alignment

The previous `BlockLayout` `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="center"` | `justifyItems="center"` | Use `justifyItems` to align items within their grid areas. |

### border

The previous `BlockLayout` `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 `BlockLayout` `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 `BlockLayout` `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 `BlockLayout` `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. |

***