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.

Choose a version:

Box

The Box component is a generic container that provides flexible layout with consistent spacing and styling. Use it to apply padding, to nest and group other components, or as the foundation for building structured layouts.

The component provides granular control over spacing through padding properties and sizing through width/height properties, serving as a building block for precise layouts. It simplifies the creation of containers with consistent spacing by using design system tokens, ensuring visual consistency and reducing the need for custom CSS in most layout scenarios.

Box components provide shorthand properties for common padding patterns like equal padding on all sides or symmetric horizontal/vertical padding, reducing verbose property specifications for simpler layouts.

Support

Targets (9)

Supported targets

Anchor to PropertiesProperties

Configure the following properties on the Box component.

Anchor to blockSize blockSize Default: 'auto': Adjusts the block size (height in horizontal writing modes). Use 'auto' to take the block size of the box's children. Learn more about block-size on MDN.
Anchor to inlineSize inlineSize Default: 'auto': Adjusts the inline size (width in horizontal writing modes). Use 'auto' to take the inline size of the box's children. Learn more about inline-size on MDN.
Anchor to maxBlockSize maxBlockSize Default: 'none': Adjusts the maximum block size (max-height in horizontal writing modes). Learn more about max-block-size on MDN.
Anchor to maxInlineSize maxInlineSize Default: 'none': Adjusts the maximum inline size (max-width in horizontal writing modes). Learn more about max-inline-size on MDN.
Anchor to minBlockSize minBlockSize Default: '0': Adjusts the minimum block size (min-height in horizontal writing modes). Learn more about min-block-size on MDN.
Anchor to minInlineSize minInlineSize Default: '0': Adjusts the minimum inline size (min-width in horizontal writing modes). Learn more about min-inline-size on MDN.
Anchor to padding padding Default: '0': Adjusts the padding on all edges of the box using predefined spacing values.
Anchor to paddingBlock paddingBlock Default: '0': Adjusts the padding on the block axis (vertical in horizontal writing modes). Overrides the block value from padding.
Anchor to paddingBlockEnd paddingBlockEnd Default: '0': Adjusts the padding at the block-end edge (bottom in horizontal writing modes). Overrides the end value from paddingBlock.
Anchor to paddingBlockStart paddingBlockStart Default: '0': Adjusts the padding at the block-start edge (top in horizontal writing modes). Overrides the start value from paddingBlock.
Anchor to paddingInline paddingInline Default: '0': Adjusts the padding on the inline axis (horizontal in horizontal writing modes). Overrides the inline value from padding.
Anchor to paddingInlineEnd paddingInlineEnd Default: '0': Adjusts the padding at the inline-end edge (right in left-to-right languages). Overrides the end value from paddingInline.
Anchor to paddingInlineStart paddingInlineStart Default: '0': Adjusts the padding at the inline-start edge (left in left-to-right languages). Overrides the start value from paddingInline.

SizeUnitsOrAuto

Extends SizeUnits to include `'auto'` for properties that can automatically size based on content.

SizeUnits | 'auto'

SizeUnits

Defines CSS size units for dimensions, supporting pixel values, percentages, or zero.

`${number}px` | `${number}%` | `0`

SizeUnitsOrNone

Extends SizeUnits to include `'none'` for properties that can be explicitly disabled.

SizeUnits | 'none'

PaddingKeys

Defines the allowed padding values, including all standardized size keywords and `'none'` for no padding.

SizeKeyword | 'none'

SizeKeyword

Defines the standardized spacing scale used throughout the POS design system. Each keyword maps to a predetermined spacing value that ensures visual consistency across components. Values range from `'0'` (no spacing) through `'2000'` (maximum spacing), with increments designed to create harmonious visual rhythm and hierarchy.

'0' | '025' | '050' | '100' | '200' | '250' | '300' | '350' | '400' | '450' | '500' | '600' | '700' | '800' | '900' | '1000' | '1100' | '1200' | '1400' | '1800' | '2000'

Anchor to ExamplesExamples

Anchor to Create a container with paddingCreate a container with padding

Create flexible layout containers with consistent spacing and styling. This example demonstrates a Box that applies padding, groups components, and provides granular control over spacing using design system tokens, serving as a foundation for structured layouts.

Create a container with padding

import React from 'react';

import {

Box,

Image,

Navigator,

Screen,

ScrollView,

reactExtension,

} from '@shopify/ui-extensions-react/point-of-sale';

const ImageModal = () => {

return (

<Box

blockSize="100px"

inlineSize="100px"

paddingInlineStart="100"

paddingInlineEnd="100"

paddingBlockEnd="100"

paddingBlockStart="100"

<Image

src="example.png"

size="contain"

</Box>

</ScrollView>

</Screen>

</Navigator>

);

};

export default reactExtension(

'pos.home.modal.render',

() => <ImageModal />,

);

import {

extend,

Navigator,

Screen,

ScrollView,

Box,

Image,

} from '@shopify/ui-extensions/point-of-sale';

export default extend(

'pos.home.modal.render',

(root) => {

const navigator =

root.createComponent(Navigator);

const imageBoxScreen =

navigator.createComponent(Screen, {

name: 'ImageBox',

title: 'ImageBox',

});

const scrollView =

imageBoxScreen.createComponent(ScrollView);

const box = scrollView.createComponent(Box, {

blockSize: '100px',

inlineSize: '100px',

paddingInlineStart: '100',

paddingInlineEnd: '100',

paddingBlockStart: '100',

paddingBlockEnd: '100',

});

const image = box.createComponent(Image, {

src: 'example.png',

size: 'contain',

});

box.appendChild(image);

scrollView.appendChild(box);

imageBoxScreen.appendChild(scrollView);

navigator.appendChild(imageBoxScreen);

root.appendChild(navigator);

);

React

import React from 'react';

import {
  Box,
  Image,
  Navigator,
  Screen,
  ScrollView,
  reactExtension,
} from '@shopify/ui-extensions-react/point-of-sale';

const ImageModal = () => {
  return (
    <Navigator>
      <Screen name="ImageBox" title="ImageBox">
        <ScrollView>
          <Box
            blockSize="100px"
            inlineSize="100px"
            paddingInlineStart="100"
            paddingInlineEnd="100"
            paddingBlockEnd="100"
            paddingBlockStart="100"
          >
            <Image
              src="example.png"
              size="contain"
            />
          </Box>
        </ScrollView>
      </Screen>
    </Navigator>
  );
};

export default reactExtension(
  'pos.home.modal.render',
  () => <ImageModal />,
);

TS

import {
  extend,
  Navigator,
  Screen,
  ScrollView,
  Box,
  Image,
} from '@shopify/ui-extensions/point-of-sale';

export default extend(
  'pos.home.modal.render',
  (root) => {
    const navigator =
      root.createComponent(Navigator);

    const imageBoxScreen =
      navigator.createComponent(Screen, {
        name: 'ImageBox',
        title: 'ImageBox',
      });

    const scrollView =
      imageBoxScreen.createComponent(ScrollView);

    const box = scrollView.createComponent(Box, {
      blockSize: '100px',
      inlineSize: '100px',
      paddingInlineStart: '100',
      paddingInlineEnd: '100',
      paddingBlockStart: '100',
      paddingBlockEnd: '100',
    });

    const image = box.createComponent(Image, {
      src: 'example.png',
      size: 'contain',
    });

    box.appendChild(image);
    scrollView.appendChild(box);
    imageBoxScreen.appendChild(scrollView);
    navigator.appendChild(imageBoxScreen);

    root.appendChild(navigator);
  },
);

Anchor to Best practicesBest practices

Apply consistent padding using the numeric scale: Use the predefined numeric padding values (for example, '100', '300', '500') to maintain consistency across your interface. Start with '300' for standard content and adjust up or down based on the visual hierarchy and spacing needs of your layout.
Use directional padding for precise control: Use specific padding properties like paddingInline and paddingBlock when you need different spacing on different sides. This is particularly useful for creating asymmetric layouts or aligning content with other interface elements.
Combine Box with other layout components strategically: Use Box as a foundation with other layout components like Stack for optimal results. Box handles spacing and sizing, while Stack manages the arrangement and alignment of child elements within the container.
Consider content flow and reading patterns: When using directional properties, remember that block refers to the main content flow direction (usually vertical) and inline refers to the text direction (usually horizontal).
Optimize for touch interfaces: Ensure adequate padding around interactive elements within Box containers. POS interfaces are primarily touch-based, so generous padding improves usability and reduces accidental interactions. Consider using padding values of '300' or higher for touch targets.

Anchor to LimitationsLimitations

Box is a layout container and doesn't provide interactive functionality—use it in combination with interactive components like Button or Clickable for user interactions.
Padding values are limited to the predefined numeric scale—custom pixel values for padding aren't supported to maintain design consistency.
Box doesn't provide scrolling capabilities for overflow content—use ScrollView when content might exceed container dimensions.

Was this page helpful?