Box

Overview

Box is a primitive component that provides direct access to Paste design tokens through props. It’s the fundamental building block that underlies most Paste components and gives you complete control over layout, spacing, colors, borders, and other style properties using design tokens. Use Box when you need:

Fine-grained control over styling using design tokens
To create custom layouts or components
Access to responsive design capabilities
To render any HTML element with Paste design token styling

Installation

npm install @twilio-paste/core

import { Box } from '@twilio-paste/core/box';
// or
import { Box } from '@twilio-paste/core';

Basic Usage

import { Box } from '@twilio-paste/core/box';
import { Text } from '@twilio-paste/core/text';

const MyComponent = () => (
  <Box
    backgroundColor="colorBackgroundPrimaryWeak"
    borderRadius="borderRadius20"
    padding="space40"
    margin="space20"
  >
    <Text as="p">Content inside a styled box</Text>
  </Box>
);

Props

keyof JSX.IntrinsicElements

default:"div"

Controls the HTML element that will be rendered in the DOM. Can be any valid HTML element like ‘div’, ‘span’, ‘section’, ‘article’, etc.

element

string

default:"BOX"

Overrides the default element name to apply unique styles with the Customization Provider. Used for customization and theming.

variant

string

Used to style custom variants via customization.

Layout Props

display

string

Sets the CSS display property. Common values: ‘block’, ‘inline’, ‘flex’, ‘inline-flex’, ‘grid’, ‘none’.

width

string

Sets width using design tokens. Can use size tokens or CSS values.

minWidth

string

Sets minimum width using design tokens.

maxWidth

string

Sets maximum width using design tokens.

height

string

Sets height using design tokens.

minHeight

string

Sets minimum height using design tokens.

maxHeight

string

Sets maximum height using design tokens.

size

string

Sets both width and height to the same value using design tokens.

overflow

string

Sets the CSS overflow property. Values: ‘visible’, ‘hidden’, ‘scroll’, ‘auto’.

Spacing Props

margin

Space

Sets margin on all sides using space design tokens (e.g., ‘space40’, ‘space80’).

marginTop

Space

Sets top margin using space design tokens.

marginRight

Space

Sets right margin using space design tokens.

marginBottom

Space

Sets bottom margin using space design tokens.

marginLeft

Space

Sets left margin using space design tokens.

marginX

Space

Sets horizontal (left and right) margin using space design tokens.

marginY

Space

Sets vertical (top and bottom) margin using space design tokens.

padding

Space

Sets padding on all sides using space design tokens.

paddingTop

Space

Sets top padding using space design tokens.

paddingRight

Space

Sets right padding using space design tokens.

paddingBottom

Space

Sets bottom padding using space design tokens.

paddingLeft

Space

Sets left padding using space design tokens.

paddingX

Space

Sets horizontal (left and right) padding using space design tokens.

paddingY

Space

Sets vertical (top and bottom) padding using space design tokens.

Background Props

backgroundColor

string

Sets background color using color design tokens (e.g., ‘colorBackgroundPrimaryWeak’).

Border Props

borderStyle

string

Sets border style. Values: ‘solid’, ‘dashed’, ‘dotted’, ‘none’.

borderColor

string

Sets border color using color design tokens (e.g., ‘colorBorderPrimary’).

borderWidth

string

Sets border width on all sides using border width tokens (e.g., ‘borderWidth10’).

borderTopWidth

string

Sets top border width using border width tokens.

borderRightWidth

string

Sets right border width using border width tokens.

borderBottomWidth

string

Sets bottom border width using border width tokens.

borderLeftWidth

string

Sets left border width using border width tokens.

borderRadius

string

Sets border radius on all corners using border radius tokens (e.g., ‘borderRadius20’).

borderTopLeftRadius

string

Sets top-left border radius using border radius tokens.

borderTopRightRadius

string

Sets top-right border radius using border radius tokens.

borderBottomLeftRadius

string

Sets bottom-left border radius using border radius tokens.

borderBottomRightRadius

string

Sets bottom-right border radius using border radius tokens.

Position Props

position

string

Sets CSS position property. Values: ‘static’, ‘relative’, ‘absolute’, ‘fixed’, ‘sticky’.

top

string

Sets top position offset.

right

string

Sets right position offset.

bottom

string

Sets bottom position offset.

left

string

Sets left position offset.

zIndex

string

Sets z-index using design tokens.

Shadow Props

boxShadow

string

Sets box shadow using shadow design tokens (e.g., ‘shadow’).

Flexbox Props

Box includes all flexbox properties when used as a flex container or flex item:

alignItems

string

Controls flex item alignment on the cross axis.

justifyContent

string

Controls flex item alignment on the main axis.

flexDirection

string

Sets flex direction. Values: ‘row’, ‘column’, ‘row-reverse’, ‘column-reverse’.

flexWrap

string

Sets flex wrapping behavior. Values: ‘nowrap’, ‘wrap’, ‘wrap-reverse’.

flex

string | number

Sets the flex shorthand property.

flexGrow

number

Sets flex grow factor.

flexShrink

number

Sets flex shrink factor.

flexBasis

string

Sets flex basis.

Grid Props

Box includes grid properties when used as a grid container:

gridTemplateColumns

string

Sets grid template columns.

gridTemplateRows

string

Sets grid template rows.

gridGap

string

Sets gap between grid items.

columnGap

string

Sets gap between grid columns.

rowGap

string

Sets gap between grid rows.

Pseudo-class Props

Box supports pseudo-class styling through special props:

_hover

BoxBaseStyleProps

Styles applied on hover state. Accepts any Box style props.

_focus

BoxBaseStyleProps

Styles applied on focus state. Accepts any Box style props.

_active

BoxBaseStyleProps

Styles applied on active state. Accepts any Box style props.

_disabled

BoxBaseStyleProps

Styles applied when disabled. Accepts any Box style props.

Responsive Design

Many Box props support responsive values by passing an array of values. Each value in the array corresponds to a breakpoint:

<Box
  backgroundColor={[
    'colorBackgroundPrimaryWeak',
    'colorBackgroundSuccessWeakest'
  ]}
  padding={['space20', 'space70']}
  height={['size10', 'size20']}
>
  <Text as="p">This box changes style at different breakpoints</Text>
</Box>

Examples

Card-like Container

<Box
  backgroundColor="colorBackgroundBody"
  borderRadius="borderRadius20"
  borderWidth="borderWidth10"
  borderStyle="solid"
  borderColor="colorBorderWeaker"
  padding="space60"
  boxShadow="shadow"
>
  <Text as="p">Card content</Text>
</Box>

Flex Container

<Box display="flex" alignItems="center" justifyContent="space-between">
  <Text>Left content</Text>
  <Text>Right content</Text>
</Box>

As Different HTML Elements

<Box as="section" padding="space80">
  <Box as="article" marginBottom="space60">
    <Text>Article content</Text>
  </Box>
</Box>

With Pseudo States

<Box
  as="button"
  backgroundColor="colorBackgroundPrimary"
  padding="space40"
  _hover={{
    backgroundColor: 'colorBackgroundPrimaryStrong',
  }}
  _focus={{
    boxShadow: 'shadowFocus',
  }}
>
  <Text color="colorTextInverse">Hover me</Text>
</Box>

Best Practices

Use Design Tokens

Always use design tokens for styling rather than arbitrary CSS values. This ensures consistency and makes your UI themeable:

// Good
<Box padding="space40" backgroundColor="colorBackgroundPrimary" />

// Avoid
<Box padding="16px" backgroundColor="#0263E0" />

Choose the Right Abstraction

While Box is powerful, consider using higher-level layout components for common patterns:

Use Flex for flexbox layouts
Use Grid for grid layouts
Use Stack for simple stacking layouts
Use Box when you need fine-grained control or these don’t fit your needs

Semantic HTML

Use the as prop to render semantically appropriate HTML elements:

<Box as="main" padding="space80">
  <Box as="article">
    <Box as="h1">Title</Box>
    <Box as="p">Content</Box>
  </Box>
</Box>

Responsive Design

Leverage responsive prop arrays for mobile-first design:

<Box
  padding={['space40', 'space60', 'space80']}
  display={['block', 'flex']}
>
  Content
</Box>

Accessibility

Use semantic HTML elements via the as prop when appropriate
Ensure sufficient color contrast when setting custom background and text colors
Don’t rely solely on color to convey information
When creating interactive elements, ensure they’re keyboard accessible

Flex - Simplified flexbox layouts
Grid - 12-column grid system
Stack - Vertical or horizontal stacking
Media Object - Media object pattern

Layout

Form Elements

Navigation

Actions

Data Display

Typography

Feedback

Overlays

Communication

Application

Utilities

Data Visualization

Content

Overview

Installation

Basic Usage

Props

Layout Props

Spacing Props

Background Props

Border Props

Position Props

Shadow Props

Flexbox Props

Grid Props

Pseudo-class Props

Responsive Design

Examples

Card-like Container

Flex Container

As Different HTML Elements

With Pseudo States

Best Practices

Use Design Tokens

Choose the Right Abstraction

Semantic HTML

Responsive Design

Accessibility

Build docs developers (and LLMs) love

Layout

Form Elements

Navigation

Actions

Data Display

Typography

Feedback

Overlays

Communication

Application

Utilities

Data Visualization

Content

​Overview

​Installation

​Basic Usage

​Props

​Layout Props

​Spacing Props

​Background Props

​Border Props

​Position Props

​Shadow Props

​Flexbox Props

​Grid Props

​Pseudo-class Props

​Responsive Design

​Examples

​Card-like Container

​Flex Container

​As Different HTML Elements

​With Pseudo States

​Best Practices

​Use Design Tokens

​Choose the Right Abstraction

​Semantic HTML

​Responsive Design

​Accessibility

​Related Components

Build docs developers (and LLMs) love

Overview

Installation

Basic Usage

Props

Layout Props

Spacing Props

Background Props

Border Props

Position Props

Shadow Props

Flexbox Props

Grid Props

Pseudo-class Props

Responsive Design

Examples

Card-like Container

Flex Container

As Different HTML Elements

With Pseudo States

Best Practices

Use Design Tokens

Choose the Right Abstraction

Semantic HTML

Responsive Design

Accessibility

Related Components