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.

Box

The Box component is a foundational layout primitive that controls padding, sizing, and visibility of its children. Use Box to add spacing around content, constrain dimensions, or toggle visibility without introducing stacking or alignment behavior.

For arranging multiple children in a vertical or horizontal flow, use BlockStack or InlineStack. For semantic grouping with a heading, use Section.

Support
Targets (46)

Supported targets

Anchor to PropertiesProperties

Props for the Box component, a generic layout container. Box doesn't define any props of its own. It inherits accessibility, sizing, padding, and display props from shared interfaces.

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 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 display
display
'auto' | 'none'
Default: 'auto'

Whether the element is rendered and takes up space in the layout.

  • auto: The element is rendered normally and participates in layout.
  • none: The element isn't rendered at all and doesn't take up any space. Use this to conditionally hide content without removing it from the component tree.
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 ExamplesExamples

Anchor to Create a padded content containerCreate a padded content container

Add padding around a warehouse slot name, aisle reference, and unit count. This example uses Box with padding inside a BlockStack to inset the slot details from the heading above.

Create a padded content container

Add padding around a warehouse slot name, aisle reference, and unit count. This example uses `Box` with `padding` inside a [BlockStack](/docs/api/admin-extensions/2025-07/ui-components/layout-and-structure/blockstack) to inset the slot details from the heading above.

Create a padded content container

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

function App() {

return (
<BlockStack gap>
<Text fontWeight="bold">Warehouse slot</Text>
<Box padding="base">
<Text fontWeight="bold">Slot A-42</Text>
<Text>Aisle A, Rack 4, Shelf 2</Text>
<Text>24 units stored</Text>
</Box>
</BlockStack>
);
}

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

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

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

const heading = root.createComponent(Text, {fontWeight: 'bold'}, 'Warehouse slot');

const card = root.createComponent(Box, {
padding: 'base',
});

const slot = root.createComponent(Text, {fontWeight: 'bold'}, 'Slot A-42');
const location = root.createComponent(Text, {}, 'Aisle A, Rack 4, Shelf 2');
const status = root.createComponent(Text, {}, '24 units stored');

card.appendChild(slot);
card.appendChild(location);
card.appendChild(status);

stack.appendChild(heading);
stack.appendChild(card);
root.appendChild(stack);
},
);

Anchor to Constrain image dimensionsConstrain image dimensions

Constrain an Image to a fixed size using inlineSize and blockSize props. This example creates a thumbnail container alongside product details in an InlineStack, preventing the image from stretching beyond its bounds.

Constrain image dimensions

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

function App() {

return (
<BlockStack gap>
<InlineStack gap>
<Box inlineSize={80} blockSize={80}>
<Image
source="https://cdn.shopify.com/s/files/placeholder-images/product.png"
accessibilityLabel="Product thumbnail"
/>
</Box>
<Box>
<Text fontWeight="bold">Premium Widget</Text>
<Text>SKU: WH-1234</Text>
<Text>$49.99</Text>
</Box>
</InlineStack>
</BlockStack>
);
}

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

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

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

const row = root.createComponent(InlineStack, {gap: true});

const imageBox = root.createComponent(Box, {
inlineSize: 80,
blockSize: 80,
});
const image = root.createComponent(Image, {
source: 'https://cdn.shopify.com/s/files/placeholder-images/product.png',
accessibilityLabel: 'Product thumbnail',
});
imageBox.appendChild(image);

const detailBox = root.createComponent(Box);
const title = root.createComponent(Text, {fontWeight: 'bold'}, 'Premium Widget');
const sku = root.createComponent(Text, {}, 'SKU: WH-1234');
const price = root.createComponent(Text, {}, '$49.99');
detailBox.appendChild(title);
detailBox.appendChild(sku);
detailBox.appendChild(price);

row.appendChild(imageBox);
row.appendChild(detailBox);

stack.appendChild(row);
root.appendChild(stack);
},
);

Anchor to Control visibility with displayControl visibility with display

Hide supplementary content from the visible layout while keeping it in the DOM. This example uses display="none" on a Box with accessibilityRole="status" to remove a compliance message visually without deleting it from the page.

Control visibility with display

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

function App() {

return (
<BlockStack gap>
<Text fontWeight="bold">Compliance status</Text>
<Box display="auto" padding="base">
<Text>This product has been reviewed and approved for sale.</Text>
</Box>
<Box display="none" accessibilityRole="status">
<Text>Compliance check passed — accessible to screen readers only.</Text>
</Box>
</BlockStack>
);
}

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

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

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

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

const visibleBox = root.createComponent(Box, {
display: 'auto',
padding: 'base',
});
const visibleText = root.createComponent(Text, {}, 'This product has been reviewed and approved for sale.');
visibleBox.appendChild(visibleText);

const hiddenBox = root.createComponent(Box, {
display: 'none',
accessibilityRole: 'status',
});
const hiddenText = root.createComponent(
Text,
{},
'Compliance check passed — accessible to screen readers only.',
);
hiddenBox.appendChild(hiddenText);

stack.appendChild(heading);
stack.appendChild(visibleBox);
stack.appendChild(hiddenBox);
root.appendChild(stack);
},
);

Anchor to Best practicesBest practices

  • Use Box for padding and sizing control: Box is most useful when you need to add padding around content or control the block and inline size of a container without the stacking behavior of BlockStack or InlineStack.
  • Prefer BlockStack and InlineStack for stacking: If you are arranging multiple children vertically or horizontally, use BlockStack or InlineStack instead of Box. Those components provide gap control and alignment that Box doesn't.

Anchor to LimitationsLimitations

  • Box doesn't support gap or spacing between children. To add spacing between child elements, use BlockStack or InlineStack instead.
  • Box doesn't render any visible background, border, or shadow. It's a transparent layout wrapper. There is no built-in way to create card-like visual containers with Box alone.
  • Box doesn't support flex direction, wrapping, or alignment props. It's not a flex container. For flex-like layouts, use BlockStack or InlineStack.
Was this page helpful?