Skip to contentSkip to navigationSkip to topbar
Figma
Star

Box

The Box primitive is one of the pillars of our system. It can be any HTML element and can receive many of our token values as props. We use Box to build most of our other components.

Version 10.3.0
Github
Component preview theme
<Box
as="article"
backgroundColor="colorBackgroundBody"
padding="space60"
>
Parent box on the hill side
<Box
backgroundColor="colorBackgroundSuccessWeakest"
display="inline-block"
padding="space40"
>
nested box 1 made out of ticky tacky
</Box>
</Box>

Guidelines

Guidelines page anchor

The Box component is one of the pillars of our system. It can be any HTML element and can receive many of our token values as props. We use Box to build most of our other components.

About Box

About Box page anchor

All HTML elements can be considered as boxes. In CSS, the term "box model" is used when talking about design and layout. It consists of: margins, borders, padding, and the actual content.

The Box component is inspired from the “box model". It is a simple wrapper component that takes tokens instead of using CSS. The limited but scoped set of tokens allowed on Box act as guardrails. They provide quick and direct access to the Twilio design language while preventing any other value. We prevent other values to protect our product from inconsistent and inaccessible designs.

For this reason, we can use the Box component to build out most of the interfaces at Twilio. Using this component will make our products resilient to design changes and themeable.

The Box component takes original inspiration from RebassJs(link takes you to an external page) and is powered by Styled System(link takes you to an external page). The pseudo class functionality was inspired by and mimics Chakra UI(link takes you to an external page).

Accessibility

Accessibility page anchor

The Box component is an all purpose component. By default, it has no accessibility concerns. If you use the Box as a custom element, it is up to you to manage the resulting accessibility implications.

(information)

Be sure to use the as prop to select semantically meaningful HTML elements. By default the Box component renders as a div which doesn’t provide much meaning to the user.

Component preview theme
<Box
as="article"
backgroundColor="colorBackgroundBody"
padding="space60"
>
Parent box on the hill side
<Box
backgroundColor="colorBackgroundSuccessWeakest"
display="inline-block"
padding="space40"
>
nested box 1 made out of ticky tacky
</Box>
<Box
backgroundColor="colorBackgroundPrimaryWeak"
display="inline-block"
padding="space40"
>
Nested box 2 may look the same
</Box>
</Box>

Tokens as pseudo-class props

Tokens as pseudo-class props page anchor

To view the full list of pseudo-class props, check the props table.

Component preview theme
<Box
backgroundColor="colorBackgroundPrimaryWeak"
padding="space60"
transition="all 200ms ease-in"
_hover={{padding: "space30", backgroundColor: "colorBackgroundPrimaryWeakest", cursor: "pointer"}}
>
Hover over me!
</Box>

The Box component is used to compose other experiences. If you imagine everything on a webpage as a Box, you can see how they all come together. Let's assume we need to build a modal component: it has a header, a body and a footer. Here's how we’ll compose the modal using Box:

Component preview theme
<Box
overflow="hidden"
borderRadius="borderRadius20"
borderStyle="solid"
borderWidth="borderWidth10"
borderColor="colorBorderPrimaryWeak"
>
<Box backgroundColor="colorBackgroundPrimaryWeak" padding="space40">
Header area
</Box>
<Box backgroundColor="colorBackgroundPrimaryWeakest" padding="space40">
Body area
<Box
width="size20"
marginTop="space30"
marginBottom="space30"
padding="space30"
>
An inner box with margin and padding
</Box>
</Box>
<Box backgroundColor="colorBackgroundPrimaryWeak" padding="space40">
Footer area
</Box>
</Box>

The Paste component library aims to cover the widest range of base use-cases. Sometimes, product requirements are more specific than what is offered here. When no other component in Paste works, use the Box component to build new experiences.

Be wary of building slightly different versions of existing Paste components. If what you need is only a little different, try to constrain the design into one of our provided solutions. This will allow you to leverage more of our system and reduce your maintenance costs. On the surface our components may look simple or restrictive. They are often limited for very specific reasons, such as accessibility.

Do

Use Box to build new components and experiences.

Don't

Use Box to build slightly different versions of existing Paste components.

Do

Use Box to layout your page or to apply padding to your components.

Don't

Use inline CSS, the CSS Cascade, or classNames to add styles that Box can provide.

Do

Use Box with an 'as' prop to style custom HTML elements with tokens.

Don't

Use HTML elements for functionality covered by the Box component.