Components/Layout
Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/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.
<Page/> component.<Layout/> and <Card/> components.Render any kind of content inside of a box. Boxes must include at least one element, and can wrap multiple child elements.
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.
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.Control the space between elements contained inside a box with gap prop. WSR spacing tokens and values are shown in pixels.
Align child elements of an X-axis inside a box with align prop as follows:
leftcenterrightspace-betweendistributes child items evenly.Align child elements of a Y-axis inside a box with verticalAlign prop as follows:
topmiddlebottomspace-between distributes child items evenly.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, andpaddingLeft which define the amount of white space from a specific side only.Control the amount of white space around the box component itself with different properties.
margin.marginTop, marginRight, marginBottom or marginLeft .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.
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.Define how a box behaves as an inline element when placed next to other components.
Use a box to arrange elements inside of other components in a desired way.
A combination of boxes can be used to construct custom widgets and list items.
| 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. |
Import the driver matching your test environment:
| 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. |
hover() to its testkit. (#17633)data-* and aria-* props now render as attributes on the root element. (#17618)Last updated: 30 October 2026