Skip to main content
Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

BlockStack

The BlockStack component arranges its children vertically (along the block axis) with configurable spacing between them. Use it to stack elements like headings, paragraphs, form fields, and buttons in a column layout.

For horizontal arrangement, use InlineStack.

Support
Targets (46)

Supported targets

Anchor to PropertiesProperties

Props for the BlockStack component, which arranges its children in a vertical stack (block axis). Use BlockStack to lay out components vertically with consistent spacing and alignment.

Anchor to accessibilityLabel
accessibilityLabel
string

A label that describes the purpose or contents of the element. When set, it will be announced to users using assistive technologies and will provide them with more context. When set, any children or label supplied won't be announced to screen readers.

Anchor to accessibilityRole
accessibilityRole
Default: 'generic'

The semantic meaning of the component’s content. When set, the role will be used by assistive technologies to help users navigate the page.

Anchor to blockAlignment
blockAlignment
Default: 'start'

The alignment of children along the block (vertical) axis within the stack. Use this to control how children are vertically distributed in a vertical stack layout.

Anchor to blockGap
blockGap
| boolean

The spacing between children along the block axis (top-to-bottom in horizontal writing modes). This is an alias for rowGap. When set to true, applies a default block gap appropriate for the component.

Anchor to blockSize
blockSize
number | `${number}%`

The block size (height in horizontal writing modes) of the element.

  • number: The size in pixels.
  • `${number}%`: The size as a percentage of the parent container's block size.

Learn more about the block-size property.

Anchor to gap
gap
< | boolean>

The spacing between children in both axes. Accepts a single value for uniform spacing, or two values separated by a space for independent block-axis and inline-axis spacing (such as "base small"). When set to true, applies a default gap appropriate for the component.

Learn more about the gap property.

Anchor to id
id
string

A unique identifier for the element.

Anchor to inlineAlignment
inlineAlignment
Default: 'start'

The alignment of children along the inline (horizontal) axis within the stack. Use this to control how children are horizontally aligned in a vertical stack layout.

Anchor to inlineSize
inlineSize
number | `${number}%`

The inline size (width in horizontal writing modes) of the element.

  • number: The size in pixels.
  • `${number}%`: The size as a percentage of the parent container's inline size.

Learn more about the inline-size property.

Anchor to maxBlockSize
maxBlockSize
number | `${number}%`

The maximum block size (maximum height in horizontal writing modes). The element won't grow taller than this value even if its content is longer.

  • number: The size in pixels.
  • `${number}%`: The size as a percentage of the parent container's block size.

Learn more about the max-block-size property.

Anchor to maxInlineSize
maxInlineSize
number | `${number}%`

The maximum inline size (maximum width in horizontal writing modes). The element won't grow wider than this value.

  • number: The size in pixels.
  • `${number}%`: The size as a percentage of the parent container's inline size.

Learn more about the max-inline-size property.

Anchor to minBlockSize
minBlockSize
number | `${number}%`

The minimum block size (minimum height in horizontal writing modes). The element won't shrink smaller than this value even if its content is shorter.

  • number: The size in pixels.
  • `${number}%`: The size as a percentage of the parent container's block size.

Learn more about the min-block-size property.

Anchor to minInlineSize
minInlineSize
number | `${number}%`

The minimum inline size (minimum width in horizontal writing modes). The element won't shrink narrower than this value.

  • number: The size in pixels.
  • `${number}%`: The size as a percentage of the parent container's inline size.

Learn more about the min-inline-size property.

Anchor to padding
padding
< | boolean>

The padding on all edges of the element, using a shorthand syntax. You can specify one to four values following the CSS shorthand convention.

When set to true, applies a default padding appropriate for the component.

Anchor to paddingBlock
paddingBlock
< | boolean>

The padding on the block-start and block-end edges. When set to true, applies a default block padding appropriate for the component.

Learn more about the padding-block property.

Anchor to paddingBlockEnd
paddingBlockEnd
| boolean

The padding on the block-end edge (the bottom edge in horizontal writing modes). When set to true, applies a default padding appropriate for the component.

Learn more about the padding-block-end property.

Anchor to paddingBlockStart
paddingBlockStart
| boolean

The padding on the block-start edge (the top edge in horizontal writing modes). When set to true, applies a default padding appropriate for the component.

Learn more about the padding-block-start property.

Anchor to paddingInline
paddingInline
< | boolean>

The padding on the inline-start and inline-end edges. When set to true, applies a default inline padding appropriate for the component.

Learn more about the padding-inline property.

Anchor to paddingInlineEnd
paddingInlineEnd
| boolean

The padding on the inline-end edge (the right edge in left-to-right writing modes). When set to true, applies a default padding appropriate for the component.

Learn more about the padding-inline-end property.

Anchor to paddingInlineStart
paddingInlineStart
| boolean

The padding on the inline-start edge (the left edge in left-to-right writing modes). When set to true, applies a default padding appropriate for the component.

Learn more about the padding-inline-start property.

Anchor to rowGap
rowGap
| boolean

The spacing between rows (children stacked along the block axis). When set to true, applies a default row gap appropriate for the component.

Learn more about the row-gap property.

Anchor to ExamplesExamples

Anchor to Stack extension content verticallyStack extension content vertically

Stack a sync status label, two detail lines, and an action button in a vertical column with consistent spacing. This example uses BlockStack with the gap prop to control the vertical rhythm, and includes a secondary Button for viewing the sync log.

Stack extension content vertically

Stack a sync status label, two detail lines, and an action button in a vertical column with consistent spacing. This example uses `BlockStack` with the `gap` prop to control the vertical rhythm, and includes a secondary [Button](/docs/api/admin-extensions/2025-07/ui-components/actions/button) for viewing the sync log.

Stack extension content vertically

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

function App() {

return (
<BlockStack gap>
<Text fontWeight="bold">Warehouse sync</Text>
<Text>Last synced 10 minutes ago</Text>
<Text>12 variants, 3 locations updated</Text>
<Button variant="secondary" onPress={() => console.log('Viewing sync log')}>
View sync log
</Button>
</BlockStack>
);
}

export default reactExtension(
'admin.product-details.block.render',
() => <App />,
);
import {extension, BlockStack, Text, Button} from '@shopify/ui-extensions/admin';

export default extension(
'admin.product-details.block.render',
(root) => {

const stack = root.createComponent(BlockStack, {gap: true});

const title = root.createComponent(Text, {fontWeight: 'bold'}, 'Warehouse sync');
const status = root.createComponent(Text, {}, 'Last synced 10 minutes ago');
const detail = root.createComponent(Text, {}, '12 variants, 3 locations updated');
const action = root.createComponent(
Button,
{variant: 'secondary', onPress: () => console.log('Viewing sync log')},
'View sync log',
);

stack.appendChild(title);
stack.appendChild(status);
stack.appendChild(detail);
stack.appendChild(action);
root.appendChild(stack);
},
);

Anchor to Center-align block contentCenter-align block content

Center a status display within the extension using inlineAlignment="center" on the BlockStack. This example centers an InlineStack of Badge indicators, creating a focused status row.

Center-align block content

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

function App() {

return (
<BlockStack gap inlineAlignment="center">
<Text fontWeight="bold">Integration status</Text>
<InlineStack gap>
<Badge tone="success">Connected</Badge>
<Badge tone="info">Auto-sync on</Badge>
</InlineStack>
<Text>247 products synced</Text>
</BlockStack>
);
}

export default reactExtension(
'admin.product-details.block.render',
() => <App />,
);
import {extension, BlockStack, Text, Badge, InlineStack} from '@shopify/ui-extensions/admin';

export default extension(
'admin.product-details.block.render',
(root) => {

const stack = root.createComponent(BlockStack, {
gap: true,
inlineAlignment: 'center',
});

const title = root.createComponent(Text, {fontWeight: 'bold'}, 'Integration status');

const badges = root.createComponent(InlineStack, {gap: true});
const connectedBadge = root.createComponent(Badge, {tone: 'success'}, 'Connected');
const syncBadge = root.createComponent(Badge, {tone: 'info'}, 'Auto-sync on');
badges.appendChild(connectedBadge);
badges.appendChild(syncBadge);

const count = root.createComponent(Text, {}, '247 products synced');

stack.appendChild(title);
stack.appendChild(badges);
stack.appendChild(count);
root.appendChild(stack);
},
);

Anchor to Add padding between sectionsAdd padding between sections

Separate compliance sections with spacing and a divider inside a block layout. This example applies padding and paddingBlock on nested BlockStack components, separated by a Divider.

Add padding between sections

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

function App() {

return (
<BlockStack gap padding="base">
<Heading>Product compliance</Heading>
<BlockStack gap paddingBlock="base">
<Text fontWeight="bold">Safety rating</Text>
<Text>UL Listed — Class II</Text>
</BlockStack>
<Divider />
<BlockStack gap paddingBlock="base">
<Text fontWeight="bold">Certifications</Text>
<Text>CE, FCC, RoHS compliant</Text>
</BlockStack>
</BlockStack>
);
}

export default reactExtension(
'admin.product-details.block.render',
() => <App />,
);
import {extension, BlockStack, Text, Heading, Divider} from '@shopify/ui-extensions/admin';

export default extension(
'admin.product-details.block.render',
(root) => {

const outer = root.createComponent(BlockStack, {
gap: true,
padding: 'base',
});

const heading = root.createComponent(Heading, {}, 'Product compliance');

const section1 = root.createComponent(BlockStack, {
gap: true,
paddingBlock: 'base',
});
const label1 = root.createComponent(Text, {fontWeight: 'bold'}, 'Safety rating');
const value1 = root.createComponent(Text, {}, 'UL Listed — Class II');
section1.appendChild(label1);
section1.appendChild(value1);

const divider = root.createComponent(Divider);

const section2 = root.createComponent(BlockStack, {
gap: true,
paddingBlock: 'base',
});
const label2 = root.createComponent(Text, {fontWeight: 'bold'}, 'Certifications');
const value2 = root.createComponent(Text, {}, 'CE, FCC, RoHS compliant');
section2.appendChild(label2);
section2.appendChild(value2);

outer.appendChild(heading);
outer.appendChild(section1);
outer.appendChild(divider);
outer.appendChild(section2);
root.appendChild(outer);
},
);

Anchor to Best practicesBest practices

  • Combine with InlineStack for complex layouts: Use BlockStack for vertical arrangement and nest InlineStack components inside it for horizontal rows, creating grid-like layouts.

Anchor to LimitationsLimitations

  • BlockStack doesn't support wrapping. All children are placed in a single column.
  • BlockStack doesn't render any visible background, border, or shadow. It is purely a layout container. For visual styling, wrap it in a Box or Section.
Was this page helpful?