Box

Components/Layout

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

Overview

Copy

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.

Copy

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.

Copy

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.
Copy

Gap

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

Copy

Horizontal alignment

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

  • left
  • center
  • right
  • space-betweendistributes child items evenly.
Copy

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.
Copy

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, andpaddingLeft which define the amount of white space from a specific side only.
Copy

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 .
Copy

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.

Copy

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.
Copy

Inline

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

Copy

Common use case examples

Content arrangement

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

Copy

List item

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

Copy

Code

Copy

Props

NameTypeDefaultDescription
align"center" | "right" | "left" | "space-between"—Defines how the children are aligned according to the X axis.
ariaLabelstring—Sets the WAI-ARIA label attribute, providing an accessible name for assistive technologies like screen readers.
backgroundColorstring—Sets a background color by a key from the color palette or natively supported value (Hex, RGB, etc.)
borderstring—Enables a border and sets its width and style. This prop doesn't include WSR color variable keys.
borderBottomColorstring—Sets a border bottom color by a key from the color palette or natively supported value (Hex, RGB, etc.)
borderColorstring—Sets a border color by a key from the color palette or natively supported value (Hex, RGB, etc.)
borderLeftColorstring—Sets a border left color by a key from the color palette or natively supported value (Hex, RGB, etc.)
borderRightColorstring—Sets a border right color by a key from the color palette or natively supported value (Hex, RGB, etc.)
borderTopColorstring—Sets a border top color by a key from the color palette or natively supported value (Hex, RGB, etc.)
childrenReactNode—Allows to render any component as a child item.
colorstring—Sets a text color by a key from the color palette or natively supported value (Hex, RGB, etc.)
data-hookstring—Accepts HTML attributes that can be used in the tests.
dataHookstring—Accepts HTML attributes that can be used in the tests.
direction"horizontal" | "vertical"—Defines how the children are ordered (horizontally or vertically)
gapstring | 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.)
heightstring | number—Sets the height of the box in pixels.
inlineboolean—Defines if the box behaves as an inline element.
marginstring | 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")
marginBottomstring | 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.
marginLeftstring | 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.
marginRightstring | 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.
marginTopstring | 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.
maxHeightstring | number—Sets the maximum height of the box in pixels.
maxWidthstring | number—Sets the maximum width of the box in pixels.
minHeightstring | number—Sets the minimum height of the box in pixels.
minWidthstring | number—Sets the minimum width of the box in pixels.
paddingstring | 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")
paddingBottomstring | 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.
paddingLeftstring | 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.
paddingRightstring | 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.
paddingTopstring | 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.
refnull | 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.
styleCSSProperties—Sets object of CSS styles.
verticalAlign"top" | "bottom" | "middle" | "space-between"—Defines how the children are aligned according to the Y axis.
widthstring | number—Sets the width of the box in pixels.

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
hover—
existsChecks whether the component found with the given data hook.
elementGets the component root element.
clickClicks on the component root element.
baseReturns 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)
  • 1.343.0 (2026-10-26) — feat: data-* and aria-* props now render as attributes on the root element. (#17618)
  • 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)
  • 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)
  • 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)
  • 1.92.1 (2024-02-05) — maintenance release, no component-specific changes

Last updated: 30 October 2026

Did this help?