Migrate BlockStack to the Polaris stack component

The Polaris stack component arranges children along the block or inline axis. It replaces the previous BlockStack component and is available as <s-stack> in API versions 2025-10 and newer. <s-stack> defaults to block direction, matching BlockStack. Note that gap defaults to 'none', whereas BlockStack spacing defaulted to 'base'. To preserve the previous spacing, set gap="base" explicitly.

Anchor to Updated propertiesUpdated properties

The following properties are different in the Polaris stack component.

Anchor to spacingspacing

The previous BlockStack spacing prop is now called gap, and the accepted values 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.

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

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

function Extension() {
  return (
    <s-stack gap="base">
      <s-text>First</s-text>
      <s-text>Second</s-text>
    </s-stack>
  );
}

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

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

function Extension() {
  return (
    <BlockStack spacing="base">
      <Text>First</Text>
      <Text>Second</Text>
    </BlockStack>
  );
}

Anchor to inlineAlignmentinlineAlignment

The previous BlockStack inlineAlignment prop is now called alignItems, which aligns children on the cross axis. The previous values ('start', 'center', 'end') are all still accepted, and alignItems also adds 'normal' and 'stretch'.

Anchor to cornerRadiuscornerRadius

The previous BlockStack cornerRadius prop is now called borderRadius, and the value format has changed.

fullyRounded is removed. Use max instead.

Anchor to borderborder

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

Anchor to borderWidthborderWidth

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

Anchor to displaydisplay

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

Anchor to paddingpadding

The previous BlockStack 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 only one axis, use paddingBlock or paddingInline instead of padding.

Anchor to SizesSizes

The size properties accept updated values in the Polaris stack component. Previous unitless number values map to pixels. For example, 300 is now '300px'.

Anchor to accessibilityRoleaccessibilityRole

Several accessibilityRole values have been renamed in the Polaris stack 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 stack also adds the following new roles:

Anchor to New propertiesNew properties

The Polaris stack component introduces the following new properties: