---
title: Box
description: >-
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.
api_version: 2025-04
api_name: pos-ui-extensions
source_url:
html: >-
https://shopify.dev/docs/api/pos-ui-extensions/2025-04/ui-components/layout-and-structure/box
md: >-
https://shopify.dev/docs/api/pos-ui-extensions/2025-04/ui-components/layout-and-structure/box.md
---
# 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 (6)
### Supported targets
* [pos.customer-details.action.render](https://shopify.dev/docs/api/pos-ui-extensions/2025-04/targets/customer-details#customer-details-action-modal-)
* [pos.draft-order-details.action.render](https://shopify.dev/docs/api/pos-ui-extensions/2025-04/targets/draft-order-details#draft-order-details-action-modal-)
* [pos.home.modal.render](https://shopify.dev/docs/api/pos-ui-extensions/2025-04/targets/home-screen#home-screen-action-modal-)
* [pos.order-details.action.render](https://shopify.dev/docs/api/pos-ui-extensions/2025-04/targets/order-details#order-details-action-modal-)
* [pos.product-details.action.render](https://shopify.dev/docs/api/pos-ui-extensions/2025-04/targets/product-details#product-details-action-modal-)
* [pos.purchase.post.action.render](https://shopify.dev/docs/api/pos-ui-extensions/2025-04/targets/post-purchase#post-purchase-action-modal-)
#### Use cases
* **Spacing and padding:** Create consistent spacing and padding around content groups.
* **Structured layouts:** Build structured layouts by nesting components within Box containers.
* **Responsive sizing:** Apply responsive sizing that adapts to different screen sizes.
* **Visual hierarchy:** Establish visual hierarchy through strategic use of padding and sizing.
## Examples
### Create 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
### Examples
* #### Create a container with padding
##### Description
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.
##### React
```tsx
import React from 'react';
import {
Box,
Image,
Navigator,
Screen,
ScrollView,
reactExtension,
} from '@shopify/ui-extensions-react/point-of-sale';
const ImageModal = () => {
return (
);
};
export default reactExtension(
'pos.home.modal.render',
() => ,
);
```
##### TS
```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);
},
);
```
## Properties
Configure the following properties on the `Box` component.
* blockSize
SizeUnitsOrAuto
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](https://developer.mozilla.org/en-US/docs/Web/CSS/block-size).
* inlineSize
SizeUnitsOrAuto
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](https://developer.mozilla.org/en-US/docs/Web/CSS/inline-size).
* maxBlockSize
SizeUnitsOrNone
Default: 'none'
Adjusts the maximum block size (max-height in horizontal writing modes). Learn more about [max-block-size on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/max-block-size).
* maxInlineSize
SizeUnitsOrNone
Default: 'none'
Adjusts the maximum inline size (max-width in horizontal writing modes). Learn more about [max-inline-size on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/max-inline-size).
* minBlockSize
SizeUnits
Default: '0'
Adjusts the minimum block size (min-height in horizontal writing modes). Learn more about [min-block-size on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/min-block-size).
* minInlineSize
SizeUnits
Default: '0'
Adjusts the minimum inline size (min-width in horizontal writing modes). Learn more about [min-inline-size on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/min-inline-size).
* padding
PaddingKeys
Default: '0'
Adjusts the padding on all edges of the box using predefined spacing values.
* paddingBlock
PaddingKeys
Default: '0'
Adjusts the padding on the block axis (vertical in horizontal writing modes). Overrides the block value from `padding`.
* paddingBlockEnd
PaddingKeys
Default: '0'
Adjusts the padding at the block-end edge (bottom in horizontal writing modes). Overrides the end value from `paddingBlock`.
* paddingBlockStart
PaddingKeys
Default: '0'
Adjusts the padding at the block-start edge (top in horizontal writing modes). Overrides the start value from `paddingBlock`.
* paddingInline
PaddingKeys
Default: '0'
Adjusts the padding on the inline axis (horizontal in horizontal writing modes). Overrides the inline value from `padding`.
* paddingInlineEnd
PaddingKeys
Default: '0'
Adjusts the padding at the inline-end edge (right in left-to-right languages). Overrides the end value from `paddingInline`.
* paddingInlineStart
PaddingKeys
Default: '0'
Adjusts the padding at the inline-start edge (left in left-to-right languages). Overrides the start value from `paddingInline`.
### SizeUnitsOrAuto
Defines size values that can be specified as exact measurements or automatic sizing. Supports pixel values, percentages, zero, or automatic sizing based on content. - \`auto\`: An automatic sizing value that expands or contracts the element to fit its content while respecting size constraints. - \`${number}px\`: An exact pixel measurement for precise, fixed sizing that remains consistent across different contexts. - \`${number}%\`: A percentage-based size relative to the parent container for responsive layouts that adapt to different screen sizes. - \`'0'\`: A zero size value that completely collapses the element in that dimension.
```ts
SizeUnits | 'auto'
```
### SizeUnits
Defines exact size measurements without automatic or unconstrained options. Limited to specific pixel values, percentages, or zero. - \`${number}px\`: An exact pixel measurement for precise sizing that remains consistent across different contexts. - \`${number}%\`: A percentage-based size relative to the parent container for responsive sizing that adapts proportionally. - \`'0'\`: A zero size value that completely eliminates any dimension in that direction.
```ts
`${number}px` | `${number}%` | `0`
```
### SizeUnitsOrNone
Defines size values that can be specified as exact measurements or no constraint. Supports pixel values, percentages, zero, or no maximum limit. - \`none\`: An unconstrained size value that allows the element to grow without restriction, limited only by available space. - \`${number}px\`: An exact pixel measurement for precise sizing limits that remain consistent across different contexts. - \`${number}%\`: A percentage-based size relative to the parent container for responsive constraints that adapt to different screen sizes. - \`'0'\`: A zero size constraint that prevents the element from having any dimension in that direction.
```ts
SizeUnits | 'none'
```
### PaddingKeys
Defines the available padding size options using numeric scale values. Provides precise control over spacing with predetermined size increments.
```ts
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.
```ts
'0' | '025' | '050' | '100' | '200' | '250' | '300' | '350' | '400' | '450' | '500' | '600' | '700' | '800' | '900' | '1000' | '1100' | '1200' | '1400' | '1800' | '2000'
```
## Best 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.
## Limitations
* 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.