Box is a component primitive that can be used to build the foundation of pretty much any other component. It keeps details like spacing, borders and colors consistent with the rest of Gestalt, while allowing the developer to focus on the content.
visuallyHidden option of the
display property can be used to prevent content from being visible while ensuring that screen readers still have access to the content. This can be useful when adding context for screen reader users, such as adding a pause to the labels of Checkboxes.
display="visuallyHidden" on Box allows for an element to be visually hidden but still be read by screen readers.
Using 'as' property
By default, the Box component renders a
div element, which is a non-semantic element that doesn't provide much meaning to the user or assistive technology. Use the
as prop to inform which semantic HTML element should be rendered by the Box component instead of a
div to ensure a more meaningful experience for both the user and the browser.
When using a Box component as a custom element, it is your responsibility to address all the accessibility implications. Both the
as properties semantically classify the Box; however, the
as prop defines a more concise way to describe the HTML element by modifying the underlying DOM element directly, which helps support both accessibility and SEO. Use the
as prop whenever possible, making sure that the prop type is semantically associated with the Box content.
Using 'role' property
role property on Box classifies the Box as the semantically appropriate HTML element through the use of an ARIA role while leaving the underlying element as a
div. For example, setting
role="banner" will designate that Box to be the equivalent of a
<header> within the page hierarchy, allowing assistive technology to classify the Box appropriately.
role property creates more specific element classification and gives the user better context on the layout of the page, especially when the ability to specify the 'as' property is not available. Learn more about ARIA roles.
marginEnd properties will account for right-to-left languages and maintain proper spacing.
Some languages (ex. Arabic, Hebrew) read from right to left (RTL) instead of from left to right. For this reason, we use
marginEnd (as opposed to left and right options) to support RTL. If specific left and right options are needed, use
marginStart is a left margin that flips to a right margin in a RTL layout.
marginEnd is a right margin that flips to a left margin in a RTL layout.
You can toggle the page direction using the button below to see this behavior.
Borders are controlled by the
borderStyle property. Specifying a size (
lg) enables a solid, light gray color in that width. Specifying
shadow adds an even box-shadow around the entire container, while
raisedBottomShadow add shadows to indicate an elevated header or footer. See the elevation foundations page for more details.
The following values can be used to change the background color of Box. Be sure to use the value that semantically matches your use case. For full details on how to use our colors, visit our Color usage page.
⚠️ Note that the previous options ('red', 'white', 'lightGray', 'gray', 'darkGray', 'green', 'pine', 'olive', 'blue', 'navy', 'midnight', 'purple', 'orchid', 'eggplant', 'maroon', 'watermelon', 'orange') are still valid but will be deprecated soon.
Colors and shadows can elevate elements within the UI. In light mode,
elevationAccent can be used when shadows or borders are not an option.
elevationRaised are only applicable in dark mode, while
shadow is only applicable in light mode. For full details, visit our Elevation foundations page.
rounding property sets a border radius for the Box. Options are
pill for fully rounded corners or 0-8 representing the radius in 4px increments.
column property allows for automatic widths based on a 12-column grid. To create responsive layouts, specify different values for
Box can also be sized using a mixture of
max/min height, and
When setting the size of a Box, the
overflow property may need to be set in order to hide or scroll content that is outside the bounds of the Box.
When content overflows the bounds of Box, there are multiple options to control the overflow behavior. The default is
overflow="visible", but the most common use case is supplying
overflow="auto" to ensure overflow content can be accessed. Learn more about CSS overflow.
Control the padding on different screen sizes by setting the
lgPadding properties. In the example, we increase the padding by 4px for every breakpoint in either all directions, the x-axis only or the y-axis only.
Auto margin is a useful tool when positioning items without using flexbox layouts. By setting any of the margin properties to "auto", the margin will extend to fill the extra space.
This can be seen below, where the 5-column width Box is centered using
margin="auto" and the 3-column width Box uses
marginStart="auto" to automatically adjust the Box to the far edge.
Position is static by default but can be made absolute. Box has helpers to help align to absolute edges (top, bottom, left, right). These can be used in combination with padding to achieve desired offsets from edges.
Using as a ref
It's possible to use Box with external elements using the CSS
z-index property by capturing those values in controlled objects. The example below shows using a
FixedZIndex for a value that comes from somewhere else, and a
CompositeZIndex to layer the Box on top of it. Visit our Z-Index documentation for more details on how to use these utility classes.
Use Flex for flexbox layouts, especially when even spacing between elements is desired, by using the
Use Container to responsively layout content with a max-width on large screens.
For proper positioning when using anchored components (Popover, Tooltip, etc.) within a container that could scroll, use ScrollBoundaryContainer.
If a tap target is needed in order to click on a portion of the page, use TapArea, since
onClick is not supported on Box.
Use Sticky if a portion of the page should stick to either the top or bottom when scrolling.