Box is the lowest-level component for binding theme-based styles to an individual element on the screen. Internally, all Braid components are made up of Boxes.
All elements rendered via Box are provided with a CSS reset to ensure that elements only have styling rules that have been explicitly specified.
By default, Box renders a div element. You can customise this via the component prop. Non-Braid props will also be forwarded to the underlying element.
<Box component="span" aria-hidden>
  ...
</Box>
The className prop supports the full clsx API.
<Box className={[styles.firstClass, styles.secondClass, styles.thirdClass]}>
  ...
</Box>
Braid components are very explicit about the properties they accept, which makes providing arbitrary data attributes not possible. Instead, all Braid components accept a data prop, allowing a single collection of data attributes to be provided.
<Box
  data={{
    testid: "customIdentifier",
  }}
  // => data-testid="customIdentifier"
>
  ...
</Box>
Box provides a suite of common CSS utility props. Styles that regularly differ across screen sizes can also be expressed as responsive props, e.g. justifyContent={{ mobile: 'center', tablet: 'flexStart' }}
These utilities are recommended where possible to reduce the amount of custom CSS in your application.
<Box
  display="flex"
  justifyContent={{ mobile: "center", tablet: "flexStart" }}
  position="absolute"
  top={0}
  left={0}
  width="full"
  height="full"
>
  ...
</Box>
display (Responsive)
"block", "flex", "inline", "inlineBlock", "none"
position (Responsive)
0, 1, 2
borderRadius (Responsive)
"full", "large", "none", "small", "standard", "xlarge"
paddingTop (Responsive)
"gutter", "large", "medium", "none", "small", "xlarge", "xsmall", "xxlarge", "xxsmall", "xxxlarge"
paddingBottom (Responsive)
"gutter", "large", "medium", "none", "small", "xlarge", "xsmall", "xxlarge", "xxsmall", "xxxlarge"
paddingRight (Responsive)
"gutter", "large", "medium", "none", "small", "xlarge", "xsmall", "xxlarge", "xxsmall", "xxxlarge"
paddingLeft (Responsive)
"gutter", "large", "medium", "none", "small", "xlarge", "xsmall", "xxlarge", "xxsmall", "xxxlarge"
marginTop (Responsive)
"gutter", "large", "medium", "none", "small", "xlarge", "xsmall", "xxlarge", "xxsmall", "xxxlarge"
marginBottom (Responsive)
"gutter", "large", "medium", "none", "small", "xlarge", "xsmall", "xxlarge", "xxsmall", "xxxlarge"
marginRight (Responsive)
"gutter", "large", "medium", "none", "small", "xlarge", "xsmall", "xxlarge", "xxsmall", "xxxlarge"
marginLeft (Responsive)
"gutter", "large", "medium", "none", "small", "xlarge", "xsmall", "xxlarge", "xxsmall", "xxxlarge"
alignItems (Responsive)
"center", "flexEnd", "flexStart"
justifyContent (Responsive)
"center", "flexEnd", "flexStart", "spaceBetween"
flexDirection (Responsive)
"column", "columnReverse", "row", "rowReverse"
flexWrap (Responsive)
"nowrap", "wrap"
flexShrink (Responsive)
0
flexGrow (Responsive)
0, 1
textAlign (Responsive)
0, 1, 2
transform (Pseudo)
"touchable"
overflow
0, 1, 2, 3
userSelect
0
outline
0
opacity
0
zIndex
0, 1, 2, "dropdown", "dropdownBackdrop", "modal", "modalBackdrop", "notification", "sticky"
cursor
0, 1
pointerEvents
0
top
0
bottom
0
left
0
right
0
height
"full", "touchable"
width
"full", "touchable"
minWidth
0
maxWidth
"large", "medium", "small", "xsmall"
transition
"fast", "touchable"
Padding can be applied in all directions using our space scale. Margin is also supported with the same syntax, but padding is recommended over margin in most cases to avoid issues with collapsing margins.
<Box paddingX="gutter" paddingY="large">
  ...
</Box>
padding
paddingX
paddingY
paddingTop
paddingRight
paddingBottom
paddingLeft
Padding and margins can also differ across screen sizes by providing responsive values, e.g. padding={{ mobile: 'small', tablet: 'medium', desktop: 'large', wide: 'xlarge' }}
Responsive padding
Box provides a series of semantic backgrounds, meaning that they are named based on their desired usage rather than what they happen to look like. This is what allows us to change colours in radically different ways across our suite of themes.
<Box background="brand">...</Box>
When a Text component is placed on a dark background, the foreground colour either inverts or lightens based on the contrast rules of Text.
When using custom backgrounds or images, this can no longer work by default. However, you can opt back into this behaviour by setting the background to either customLight or customDark.
Text on custom dark background
Text on custom light background
body
Used for elements that need to match the body background.
brand
Used for branding larger areas of the screen.
brandAccent
Used for hero elements on the screen.
brandAccentHover
Hover colour for “brandAccent” elements.
brandAccentActive
Active colour for “brandAccent” elements.
brandAccentSoft
Used for soft “brandAccent” elements
brandAccentSoftActive
Active colour for “brandAccentSoft” elements.
brandAccentSoftHover
Hover colour for brandAccentSoft” elements.
formAccent
Used for prominent interactive elements, typically within a form.
formAccentHover
Hover colour for “formAccent” elements.
formAccentActive
Active colour for “formAccent” elements.
formAccentSoft
Used for soft “formAccent” elements
formAccentSoftActive
Active colour for “formAccentSoft” elements.
formAccentSoftHover
Hover colour for formAccentSoft” elements.
positive
Used for heavier “positive” elements.
positiveLight
Used for light “positive” elements.
critical
Used for heavier “critical” elements.
criticalHover
Hover colour for “critical” elements.
criticalActive
Active colour for “critical” elements.
criticalLight
Used for light “critical” elements.
criticalSoft
Used for soft “critical” elements
criticalSoftActive
Active colour for “criticalSoft” elements.
criticalSoftHover
Hover colour for criticalSoft” elements.
caution
Used for heavier “caution” elements.
cautionLight
Used for light “caution” elements.
info
Used for heavier “info” elements.
infoLight
Used for light “info” elements.
promote
Used for heavier “promote” elements.
promoteLight
Used for light “promote” elements.
neutral
Used for heavier “neutral” elements.
neutralActive
Active colour for "neutral" elements
neutralHover
Hover colour for "neutral" elements
neutralLight
Used for light “neutral” elements.
neutralSoft
Used for soft “neutral” elements
neutralSoftActive
Active colour for "neutralSoft" elements
neutralSoftHover
Hover colour for "neutralSoft" elements
surface
Used for surfaces that sit on top of body elements
Box provides a series of boxShadow values that handle a wide variety of use cases. Note that box shadows are also used for outlines and borders so that their presence doesn’t alter the dimensions of the element.
<Box boxShadow="large">...</Box>
small
Used for small shadows.
medium
Used for medium shadows.
large
Used for large shadows.
borderNeutral
Used for neutral element borders.
borderNeutralLarge
Used for large neutral element borders.
borderNeutralInverted
Used for neutral borders on dark backgrounds.
borderNeutralInvertedLarge
Used for large neutral borders on dark backgrounds.
borderNeutralLight
Used for light neutral element borders.
borderField
Used for borders around form fields.
outlineFocus
Used for focus states of interactive elements.
borderFormAccent
Used for borders around prominent interactive elements.
borderFormAccentLarge
Used for large borders around prominent interactive elements.
borderFormAccentLight
Used for borders around prominent interactive elements in a dark context.
borderFormAccentLightLarge
Used for large borders around prominent interactive elements in a dark context.
borderBrandAccent
Used for borders around branded elements.
borderBrandAccentLarge
Used for large borders around branded elements.
borderBrandAccentLight
Used for borders around branded elements in a dark context.
borderBrandAccentLightLarge
Used for large borders around branded elements in a dark context.
borderPositive
Used for borders around “positive” elements.
borderPositiveLight
Used for borders around “positiveLight” elements.
borderCritical
Used for borders around “critical” elements.
borderCriticalLarge
Used for large borders around “critical” elements.
borderCriticalLight
Used for borders around “criticalLight” elements.
borderCriticalLightLarge
Used for large borders around “criticalLight” elements.
borderCaution
Used for borders around “caution” elements.
borderCautionLight
Used for borders around “cautionLight” elements.
borderInfo
Used for borders around “info” elements.
borderInfoLight
Used for borders around “infoLight” elements.
borderPromote
Used for borders around “promote” elements.
borderPromoteLight
Used for borders around “promoteLight” elements.