> To build a Wix site agentically, or add Wix features like bookings or a store to a site you already have, follow https://www.wix.com/headless/skill.md
> 
> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Box Component

## Article: Box Component

## Article Link: https://dev.wix.com/docs/wix-design-system/components/layout/box-component.md

## Article Content:

# Box

_Components/Layout_

Interactive docs page: <https://wix-pages.com/design-system-documentation/#/component/box>

## Overview

```jsx
<Box height={180}>
  <StorybookComponents.Placeholder />
</Box>;
```

A box is a container that allows the layout, alignment, spacing and style of its child elements. Boxes can wrap and apply CSS styles to one or more elements that are contained inside.

A box renders `data-*` and `aria-*` props as attributes on its root element and forwards div event handlers, such as `onClick`, `onKeyDown`, and `onPointerEnter`, to that element. It applies any other prop it doesn't define as a CSS style.

### Do

- Arrange elements vertically or horizontally.
- Apply custom spacing and styles.
- Build custom widgets.

### Don't

- Don't use a box to build page layouts, instead use the `<Page/>` component.
- Don't use a box to build the structure of the content inside a page. To build page structures, use a combination of `<Layout/>` and `<Card/>` components.

### Feature examples

#### Structure

Render any kind of content inside of a box. Boxes must include at least one element, and can wrap multiple child elements.

```jsx
<Box>
  <StorybookComponents.Placeholder>Content</StorybookComponents.Placeholder>
</Box>;
```

#### Dimensions

Control the component size by setting its `width` and `height` in pixels or percentage. The box container size will automatically equal the size of content added inside if these values are not specified.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <Box width="100%" height="100px">
    <StorybookComponents.Placeholder>
      Width 100%, Height 100px
    </StorybookComponents.Placeholder>
  </Box>
  <Box width="50%" height="50px">
    <StorybookComponents.Placeholder>
      Width 50%, Height 50px
    </StorybookComponents.Placeholder>
  </Box>
</StorybookComponents.Stack>;
```

#### Direction

Control the `direction` in which child elements will be listed inside a box. There are 2 types of directions supported:

- `horizontal` lists items in a single row.
- `vertical` lists items in a single column. This layout will automatically extend each item to the full width of the box.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <Box direction="horizontal">
    <StorybookComponents.Placeholder>
      Horizontal
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder>
      Horizontal
    </StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder>
      Horizontal
    </StorybookComponents.Placeholder>
  </Box>
  <Box direction="vertical">
    <StorybookComponents.Placeholder>Vertical</StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder>Vertical</StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder>Vertical</StorybookComponents.Placeholder>
  </Box>
</StorybookComponents.Stack>;
```

#### Gap

Control the space between elements contained inside a box with `gap` prop. WSR spacing tokens and values are shown in pixels.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <Box gap="SP1">
    <StorybookComponents.Placeholder>6px gap</StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder>6px gap</StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder>6px gap</StorybookComponents.Placeholder>
  </Box>
  <Box gap="48px">
    <StorybookComponents.Placeholder>48px gap</StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder>48px gap</StorybookComponents.Placeholder>
    <StorybookComponents.Placeholder>48px gap</StorybookComponents.Placeholder>
  </Box>
</StorybookComponents.Stack>;
```

#### Horizontal alignment

Align child elements of an X-axis inside a box with `align` prop as follows:

- `left`
- `center`
- `right`
- `space-between`distributes child items evenly.

```jsx
<StorybookComponents.Stack>
  <StorybookComponents.Placeholder>
    <Box align="left">Left</Box>
  </StorybookComponents.Placeholder>
  <StorybookComponents.Placeholder>
    <Box align="center">Center</Box>
  </StorybookComponents.Placeholder>
  <StorybookComponents.Placeholder>
    <Box align="right">Right</Box>
  </StorybookComponents.Placeholder>
  <StorybookComponents.Placeholder>
    <Box align="space-between">
      <Box>Space</Box>
      <Box>Between</Box>
    </Box>
  </StorybookComponents.Placeholder>
</StorybookComponents.Stack>;
```

#### Vertical alignment

Align child elements of a Y-axis inside a box with `verticalAlign` prop as follows:

- `top`
- `middle`
- `bottom`
- `space-between` distributes child items evenly.

```jsx
<StorybookComponents.Stack>
  <StorybookComponents.Placeholder height="50px">
    <Box verticalAlign="top" height="100%">
      Top
    </Box>
  </StorybookComponents.Placeholder>
  <StorybookComponents.Placeholder height="50px">
    <Box verticalAlign="middle" height="100%">
      Middle
    </Box>
  </StorybookComponents.Placeholder>
  <StorybookComponents.Placeholder height="50px">
    <Box verticalAlign="bottom" height="100%">
      Bottom
    </Box>
  </StorybookComponents.Placeholder>
  <StorybookComponents.Placeholder height="50px">
    <Box verticalAlign="space-between" direction="vertical" height="100%">
      <Box>Space</Box>
      <Box>Between</Box>
    </Box>
  </StorybookComponents.Placeholder>
</StorybookComponents.Stack>;
```

#### Padding

Control the amount of white space around child elements inside a box. Padding can be defined by:

- `padding` which defines the amount of white space from all sides.
- `paddingTop`, `paddingRight`, `paddingBottom`, and`paddingLeft` which define the amount of white space from a specific side only.

```jsx
<StorybookComponents.Stack>
  <StorybookComponents.Placeholder>
    <Box padding="SP4">Equal padding</Box>
  </StorybookComponents.Placeholder>
  <StorybookComponents.Placeholder>
    <Box
      paddingTop="SP2"
      paddingRight="SP10"
      paddingBottom="SP2"
      paddingLeft="SP10"
    >
      Different side paddings
    </Box>
  </StorybookComponents.Placeholder>
  <StorybookComponents.Placeholder>
    <Box>No padding</Box>
  </StorybookComponents.Placeholder>
</StorybookComponents.Stack>;
```

#### Margin

Control the amount of white space around the box component itself with different properties.

- Define the amount of space from all sides with `margin`.
- Define the amount of space for a specific side only with `marginTop`, `marginRight`, `marginBottom` or `marginLeft` .

```jsx
<StorybookComponents.Stack>
  <Box height="18px" width="100%">
    <StorybookComponents.Placeholder>No margin</StorybookComponents.Placeholder>
  </Box>
  <Box height="18px" width="100%" margin="SP6 SP2">
    <StorybookComponents.Placeholder>
      With margin
    </StorybookComponents.Placeholder>
  </Box>
</StorybookComponents.Stack>;
```

#### Color

Control the background and text color of a component with:

- `backgroundColor` to specify the background fill color.
- `color` to specify the text color.

Properties include WSR color variables and natively supported values, such as HEX, RGB, etc.

```jsx
<StorybookComponents.Stack>
  <Box padding="SP4" margin="SP2" backgroundColor="D80" color="D10">
    Dark text
  </Box>
  <Box padding="SP4" margin="SP2" backgroundColor="D10" color="D80">
    Light text
  </Box>
  <Box padding="SP4" margin="SP2" backgroundColor="B10" color="D80">
    Light text
  </Box>
  <Box padding="SP4" margin="SP2" backgroundColor="G10" color="D80">
    Light text
  </Box>
  <Box padding="SP4" margin="SP2" backgroundColor="Y10" color="D10">
    Dark text
  </Box>
</StorybookComponents.Stack>;
```

#### Border

Control the style of a border with the following properties:

- `border` enables a border and sets its width and style. This prop does not include WSR color variable keys.
- `borderColor` specifies the border color.
- `borderTopColor`, `borderRightColor`, `borderBottomColor`, `borderLeftColor` specifies the border color per edge.
- `borderRadius` specifies the corner radius.

```jsx
<StorybookComponents.Stack>
  <Box
    padding="SP6"
    margin="SP1"
    border="1px solid"
    borderColor="D50"
    borderRadius={0}
  ></Box>
  <Box
    padding="SP6"
    margin="SP1"
    border="2px dotted"
    borderColor="D40"
    borderRadius={6}
  ></Box>
  <Box
    padding="SP6"
    margin="SP1"
    border="3px dashed"
    borderColor="D30"
    borderRadius={12}
  ></Box>
  <Box
    padding="SP6"
    margin="SP1"
    border="6px solid"
    borderColor="D20"
    borderRadius={72}
  ></Box>
</StorybookComponents.Stack>;
```

#### Inline

Define how a box behaves as an inline element when placed next to other components.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <Text>
    This is a sentence with an action at the end of it.
    <Box>
      <TextButton>Add link</TextButton>
    </Box>
  </Text>
  <Text>
    This is a sentence with an action at the end of it.
    <Box inline>
      <TextButton>Add link</TextButton>
    </Box>
  </Text>
</StorybookComponents.Stack>;
```

### Common use case examples

#### Content arrangement

Use a box to arrange elements inside of other components in a desired way.

```jsx
() => (
  <TableListItem
    options={[
      {
        value: (
          <Box verticalAlign="middle">
            <Image width="48px" height="48px" />
            <Box marginLeft="SP3" direction="vertical">
              <Heading size="small">Structured data</Heading>
              <Text size="small" secondary>
                Make your product eligible for rich results in search engines.
              </Text>
            </Box>
          </Box>
        ),
        width: '80%',
      },
      {
        value: (
          <IconButton skin="inverted">
            <Icons.ChevronDown />
          </IconButton>
        ),
        align: 'right',
      },
    ]}
  />
);
```

#### List item

A combination of boxes can be used to construct custom widgets and list items.

```jsx
() => (
  <Box height={160}>
    <Box align="center" verticalAlign="middle" width={180}>
      <Image
        height="180px"
        borderRadius="8px 0px 0px 8px"
        src="running_man.png"
      />
    </Box>
    <Box
      direction="vertical"
      borderRadius="0px 8px 8px 0px"
      verticalAlign="space-between"
      padding="18px 24px"
      backgroundColor="D80"
      flexGrow={1}
    >
      <Box verticalAlign="space-between" flexGrow={1}>
        <Box direction="vertical" gap="3px">
          <Heading size="small">Get running!</Heading>
          <Text size="small" secondary>
            Scheduled for April 26, 2021
          </Text>
        </Box>
      </Box>
      <Box align="space-between">
        <Box gap="24px">
          <Box verticalAlign="middle" gap="0px">
            <Icons.LockUnlockedSmall />
            <Box marginLeft={1}>
              <Text size="small">Public</Text>
            </Box>
          </Box>
          <Box verticalAlign="middle">
            <Box marginLeft={1}>
              <Text size="small">Join for Free</Text>
            </Box>
          </Box>
        </Box>
        <Box>
          <Box verticalAlign="middle">
            <Box gap="SP2">
              <IconButton priority="secondary" size="small">
                <Icons.MoreSmall />
              </IconButton>
              <Button priority="secondary" size="small">
                Edit
              </Button>
            </Box>
          </Box>
        </Box>
      </Box>
    </Box>
  </Box>
);
```

## Code

```jsx
import { Box } from '@wix/design-system';
```

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"center" \| "right" \| "left" \| "space-between"` | — | Defines how the children are aligned according to the X axis. |
| `ariaLabel` | `string` | — | Sets the WAI-ARIA label attribute, providing an accessible name for assistive technologies like screen readers. |
| `backgroundColor` | `string` | — | Sets a background color by a key from the color palette or natively supported value (Hex, RGB, etc.) |
| `border` | `string` | — | Enables a border and sets its width and style. This prop doesn't include WSR color variable keys. |
| `borderBottomColor` | `string` | — | Sets a border bottom color by a key from the color palette or natively supported value (Hex, RGB, etc.) |
| `borderColor` | `string` | — | Sets a border color by a key from the color palette or natively supported value (Hex, RGB, etc.) |
| `borderLeftColor` | `string` | — | Sets a border left color by a key from the color palette or natively supported value (Hex, RGB, etc.) |
| `borderRightColor` | `string` | — | Sets a border right color by a key from the color palette or natively supported value (Hex, RGB, etc.) |
| `borderTopColor` | `string` | — | Sets a border top color by a key from the color palette or natively supported value (Hex, RGB, etc.) |
| `children` | `ReactNode` | — | Allows to render any component as a child item. |
| `color` | `string` | — | Sets a text color by a key from the color palette or natively supported value (Hex, RGB, etc.) |
| `data-hook` | `string` | — | Accepts HTML attributes that can be used in the tests. |
| `dataHook` | `string` | — | Accepts HTML attributes that can be used in the tests. |
| `direction` | `"horizontal" \| "vertical"` | — | Defines how the children are ordered (horizontally or vertically) |
| `gap` | `string \| number` | — | Sets the gaps/gutters between flex items. Accepts a numeric value (multiplied by spacing unit), predefined spacing value (tiny, small, etc.) a spacing token (SP1, SP2, etc.) |
| `height` | `string \| number` | — | Sets the height of the box in pixels. |
| `inline` | `boolean` | — | Defines if the box behaves as an inline element. |
| `margin` | `string \| number` | — | Sets margin on all sides. Accepts a numeric value (multiplied by spacing unit), predefined spacing value (tiny, small, etc.) a spacing token (SP1, SP2, etc.) or a string of space-separated values ("3px 3px") |
| `marginBottom` | `string \| number` | — | Sets margin on the bottom. Accepts a numeric value (multiplied by spacing unit), predefined spacing value (tiny, small, etc.) a spacing token (SP1, SP2, etc.) or a value in pixels. |
| `marginLeft` | `string \| number` | — | Sets margin on the left. Accepts a numeric value (multiplied by spacing unit), predefined spacing value (tiny, small, etc.) a spacing token (SP1, SP2, etc.) or a value in pixels. |
| `marginRight` | `string \| number` | — | Sets margin on the right. Accepts a numeric value (multiplied by spacing unit), predefined spacing value (tiny, small, etc.) a spacing token (SP1, SP2, etc.) or a value in pixels. |
| `marginTop` | `string \| number` | — | Sets margin on the top. Accepts a numeric value (multiplied by spacing unit), predefined spacing value (tiny, small, etc.) a spacing token (SP1, SP2, etc.) or a value in pixels. |
| `maxHeight` | `string \| number` | — | Sets the maximum height of the box in pixels. |
| `maxWidth` | `string \| number` | — | Sets the maximum width of the box in pixels. |
| `minHeight` | `string \| number` | — | Sets the minimum height of the box in pixels. |
| `minWidth` | `string \| number` | — | Sets the minimum width of the box in pixels. |
| `padding` | `string \| number` | — | Sets padding on all sides. Accepts a numeric value (multiplied by spacing unit), predefined spacing value (tiny, small, etc.) a spacing token (SP1, SP2, etc.) or a string of space-separated values ("3px 3px") |
| `paddingBottom` | `string \| number` | — | Sets padding on the bottom. Accepts a numeric value (multiplied by spacing unit), predefined spacing value (tiny, small, etc.) a spacing token (SP1, SP2, etc.) or a value in pixels. |
| `paddingLeft` | `string \| number` | — | Sets padding on the left. Accepts a numeric value (multiplied by spacing unit), predefined spacing value (tiny, small, etc.) a spacing token (SP1, SP2, etc.) or a value in pixels. |
| `paddingRight` | `string \| number` | — | Sets padding on the right. Accepts a numeric value (multiplied by spacing unit), predefined spacing value (tiny, small, etc.) a spacing token (SP1, SP2, etc.) or a value in pixels. |
| `paddingTop` | `string \| number` | — | Sets padding on the top. Accepts a numeric value (multiplied by spacing unit), predefined spacing value (tiny, small, etc.) a spacing token (SP1, SP2, etc.) or a value in pixels. |
| `ref` | `null \| string \| (instance: any) => void \| RefObject<any>` | — | Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref). |
| `role` | `"article" \| "button" \| "dialog" \| "figure" \| "form" \| "img" \| "link" \| "main" \| "menu" \| "menuitem" \| "option" \| "search" \| "table" \| "switch" \| "status" \| "scrollbar" \| "checkbox" \| "none" \| "list" \| string & {} \| "alert" \| "alertdialog" \| "application" \| "banner" \| "cell" \| "columnheader" \| "combobox" \| "complementary" \| "contentinfo" \| "definition" \| "directory" \| "document" \| "feed" \| "grid" \| "gridcell" \| "group" \| "heading" \| "listbox" \| "listitem" \| "log" \| "marquee" \| "math" \| "menubar" \| "menuitemcheckbox" \| "menuitemradio" \| "navigation" \| "note" \| "presentation" \| "progressbar" \| "radio" \| "radiogroup" \| "region" \| "row" \| "rowgroup" \| "rowheader" \| "searchbox" \| "separator" \| "slider" \| "spinbutton" \| "tab" \| "tablist" \| "tabpanel" \| "term" \| "textbox" \| "timer" \| "toolbar" \| "tooltip" \| "tree" \| "treegrid" \| "treeitem"` | — | Sets the WAI-ARIA role attribute for accessibility. When set to 'button' or 'link', the box automatically receives tabIndex=0 for keyboard navigation. |
| `style` | `CSSProperties` | — | Sets object of CSS styles. |
| `verticalAlign` | `"top" \| "bottom" \| "middle" \| "space-between"` | — | Defines how the children are aligned according to the Y axis. |
| `width` | `string \| number` | — | Sets the width of the box in pixels. |

## Testkit

Import the driver matching your test environment:

```jsx
// UniDriver
import { BoxUniDriver } from '@wix/design-system/dist/testkit/unidriver';

// Vanilla
import { BoxTestkit } from '@wix/design-system/dist/testkit';

// Puppeteer
import { BoxTestkit } from '@wix/design-system/dist/testkit/puppeteer';

// Testing Library
import { BoxTestkit } from '@wix/design-system/dist/testkit/testing-library';
```

### Driver methods

| Method | Description |
| --- | --- |
| `hover` | — |
| `exists` | Checks whether the component found with the given data hook. |
| `element` | Gets the component root element. |
| `click` | Clicks on the component root element. |
| `base` | Returns UniDriver for the base element. |

## Changelog

- **1.344.0** (2026-10-28) — feat: support div event handlers, including click, keyboard, pointer, and capture handlers, and add `hover()` to its testkit. ([#17633](invalid-url))
- **1.343.0** (2026-10-26) — feat: `data-*` and `aria-*` props now render as attributes on the root element. ([#17618](invalid-url))
- **1.340.0** (2026-10-21) — maintenance release, no component-specific changes
- **1.339.0** (2026-10-19) — maintenance release, no component-specific changes
- **1.338.0** (2026-10-15) — maintenance release, no component-specific changes
- **1.330.0** (2026-09-28) — maintenance release, no component-specific changes
- **1.329.0** (2026-09-24) — maintenance release, no component-specific changes
- **1.325.0** (2026-09-17) — maintenance release, no component-specific changes
- **1.310.0** (2026-08-10) — maintenance release, no component-specific changes
- **1.295.0** (2026-07-03) — maintenance release, no component-specific changes
- **1.292.0** (2026-06-22) — maintenance release, no component-specific changes
- **1.291.0** (2026-06-19) — maintenance release, no component-specific changes
- **1.289.0** (2026-06-17) — maintenance release, no component-specific changes
- **1.286.0** (2026-06-08) — maintenance release, no component-specific changes
- **1.277.0** (2026-05-07) — maintenance release, no component-specific changes
- **1.272.0** (2026-04-27) — maintenance release, no component-specific changes
- **1.271.0** (2026-04-22) — maintenance release, no component-specific changes
- **1.266.0** (2026-04-07) — maintenance release, no component-specific changes
- **1.260.0** (2026-03-17) — maintenance release, no component-specific changes
- **1.254.0** (2026-02-03) — maintenance release, no component-specific changes
- **1.241.0** (2025-12-17) — maintenance release, no component-specific changes
- **1.240.0** (2025-12-16) — maintenance release, no component-specific changes
- **1.238.0** (2025-12-10) — feat: add A11y and navigation attributes ([#15643](invalid-url))
- **1.224.0** (2025-10-30) — maintenance release, no component-specific changes
- **1.188.1** (2025-05-14) — maintenance release, no component-specific changes
- **1.169.0** (2025-03-10) — maintenance release, no component-specific changes
- **1.148.0** (2024-12-16) — fix: add missing check ([#14396](invalid-url))
- **1.145.0** (2024-12-09) — maintenance release, no component-specific changes
- **1.138.1** (2024-10-30) — maintenance release, no component-specific changes
- **1.115.0** (2024-07-17) — maintenance release, no component-specific changes
- **1.102.0** (2024-04-16) — maintenance release, no component-specific changes
- **1.98.0** (2024-03-15) — fix: fix type definition to exclude some CSS properties ([#13472](invalid-url))
- **1.92.1** (2024-02-05) — maintenance release, no component-specific changes