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.
Props
Best practices
Use Box as a building block when creating other components or layouts that do not rely on flexbox. The included properties should cover any variations needed to create a diverse range of options.
If you find yourself using Box for flexbox layouts, consider Flex instead.
Don’t use the onClick
, className
and style
properties.
Box is a pass-through component, meaning that any other properties you provide to it will be directly applied to the underlying <div>
. The above properties are exceptions, however. We don’t allow onClick
for accessibility reasons, so consider a Button or TapArea instead. We remove className
and style
to ensure style encapsulation. If necessary, dangerouslySetInlineStyle
can be used to supply a style not supported by Box props.
If you need to use these features for animation purposes, use a <div>
instead.
When addressing the spacing of the Box, use padding before you use margins, as padding will compose better and won't collapse. Padding is applied in 4px increments and is always symmetric. Learn more about margin collapsing.
Avoid using arbitrary <div>
elements. Instead, when building a component, prioritize using Box. If you need to set a custom style, you can do so using the dangerouslySetInlineStyle
prop. However, this should be avoided whenever possible by utilizing the other props provided in Box. We provide a lint rule to prevent this from happening.
Accessibility
The 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.
Setting 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 role
and 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.
Review the available options for the as prop. For some of the options, like nav
, you will also need to specify a title
to ensure unique landmarks on the page. Learn more about semantics in HTML.
Using 'role' property
Setting the 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.
Using the 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.
Localization
Utilizing the marginStart
and marginEnd
properties will account for right-to-left languages and maintain proper spacing.
Page direction
Some languages (ex. Arabic, Hebrew) read from right to left (RTL) instead of from left to right. For this reason, we use marginStart
and marginEnd
(as opposed to left and right options) to support RTL. If specific left and right options are needed, use dangerouslySetInlineStyle
.
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.
Variants
Borders
Borders are controlled by the borderStyle
property. Specifying a size (sm
or lg
) enables a solid, light gray color in that width. Specifying shadow
adds an even box-shadow around the entire container, while raisedTopShadow
and raisedBottomShadow
add shadows to indicate an elevated header or footer. See the elevation foundations page for more details.
Colors
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.
Elevation
Colors and shadows can elevate elements within the UI. In light mode, elevationAccent
can be used when shadows or borders are not an option. elevationFloating
and elevationRaised
are only applicable in dark mode, while shadow
is only applicable in light mode. For full details, visit our Elevation foundations page.
Rounding
The rounding
property sets a border radius for the Box. Options are circle
or pill
for fully rounded corners or 0-8 representing the radius in 4px increments.
Opacity
Column layout
The column
property allows for automatic widths based on a 12-column grid. To create responsive layouts, specify different values for smColumn
, mdColumn
, and lgColumn
.
Sizing
Box can also be sized using a mixture of width
, height
, max/min width
, max/min height
, and fit
.
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.
Overflow
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.
Responsive padding
Control the padding on different screen sizes by setting the smPadding
, mdPadding
or 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 margins
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.
Absolute positioning
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
The ref
property can be used to anchor a Popover to a Box.
Z-Index
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.
Related
Flex
Use Flex for flexbox layouts, especially when even spacing between elements is desired, by using the gap
property.
Container
Use Container to responsively layout content with a max-width on large screens.
ScrollBoundaryContainer
For proper positioning when using anchored components (Popover, Tooltip, etc.) within a container that could scroll, use ScrollBoundaryContainer.
TapArea
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.
Sticky
Use Sticky if a portion of the page should stick to either the top or bottom when scrolling.