Box

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.

Semantic elements

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>

Dynamic CSS classes

The className prop supports the full clsx API.

<Box className={[styles.firstClass, styles.secondClass, styles.thirdClass]}>
  ...
</Box>

Data attributes

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.

While Box does support the native HTML syntax, it also supports the data prop for consistency.

<Box
  data={{
    testid: "customIdentifier",
  }}
  // => data-testid="customIdentifier"
>
  ...
</Box>

CSS utilities

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"

gap (Responsive)"gutter", "large", "medium", "none", "small", "xlarge", "xsmall", "xxlarge", "xxsmall", "xxxlarge"

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"auto", "hidden", "scroll", "visible"

userSelect"none"

outline"none"

opacity0

zIndex0, 1, 2, "dropdown", "dropdownBackdrop", "modal", "modalBackdrop", "notification", "sticky"

cursor"default", "pointer"

pointerEvents"none"

top0

bottom0

left0

right0

height"full", "touchable"

width"full", "touchable"

minWidth0

maxWidth"content", "large", "medium", "small", "xsmall"

transition"fast", "touchable"

Padding and margins

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

Open in Playroom

Responsive padding and margins

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

Open in Playroom

Backgrounds

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

Open in Playroom

These background colours are likely to change over time, so it’s important that you only use them within the semantic context they were designed for, e.g. only using the “selection” colour for actual user selections. If you choose colours based solely on their appearance, your application’s colours may change in unexpected ways when upgrading Braid.

bodyUsed for elements that need to match the body background.

brandUsed for branding larger areas of the screen.

brandAccentUsed for hero elements on the screen.

brandAccentHoverHover colour for “brandAccent” elements.

brandAccentActiveActive colour for “brandAccent” elements.

brandAccentSoftUsed for soft “brandAccent” elements

brandAccentSoftActiveActive colour for “brandAccentSoft” elements.

brandAccentSoftHoverHover colour for brandAccentSoft” elements.

formAccentUsed for prominent interactive elements, typically within a form.

formAccentHoverHover colour for “formAccent” elements.

formAccentActiveActive colour for “formAccent” elements.

formAccentSoftUsed for soft “formAccent” elements

formAccentSoftActiveActive colour for “formAccentSoft” elements.

formAccentSoftHoverHover colour for formAccentSoft” elements.

positiveUsed for heavier “positive” elements.

positiveLightUsed for light “positive” elements.

criticalUsed for heavier “critical” elements.

criticalHoverHover colour for “critical” elements.

criticalActiveActive colour for “critical” elements.

criticalLightUsed for light “critical” elements.

criticalSoftUsed for soft “critical” elements

criticalSoftActiveActive colour for “criticalSoft” elements.

criticalSoftHoverHover colour for criticalSoft” elements.

cautionUsed for heavier “caution” elements.

cautionLightUsed for light “caution” elements.

infoUsed for heavier “info” elements.

infoLightUsed for light “info” elements.

promoteUsed for heavier “promote” elements.

promoteLightUsed for light “promote” elements.

neutralUsed for heavier “neutral” elements.

neutralActiveActive colour for "neutral" elements

neutralHoverHover colour for "neutral" elements

neutralLightUsed for light “neutral” elements.

neutralSoftUsed for soft “neutral” elements

neutralSoftActiveActive colour for "neutralSoft" elements

neutralSoftHoverHover colour for "neutralSoft" elements

surfaceUsed for surfaces that sit on top of body elements

Shadows, borders and outlines

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>

These box shadows are likely to change over time, so it’s important that you only use them within the semantic context they were designed for, e.g. only using “borderField” for actual field borders. If you choose semantic box shadows based solely on their appearance, your application’s colours may change in unexpected ways when upgrading Braid.

smallUsed for small shadows.

mediumUsed for medium shadows.

largeUsed for large shadows.

borderNeutralUsed for neutral element borders.

borderNeutralLargeUsed for large neutral element borders.

borderNeutralInvertedUsed for neutral borders on dark backgrounds.

borderNeutralInvertedLargeUsed for large neutral borders on dark backgrounds.

borderNeutralLightUsed for light neutral element borders.

borderFieldUsed for borders around form fields.

outlineFocusUsed for focus states of interactive elements.

borderFormAccentUsed for borders around prominent interactive elements.

borderFormAccentLargeUsed for large borders around prominent interactive elements.

borderFormAccentLightUsed for borders around prominent interactive elements in a dark context.

borderFormAccentLightLargeUsed for large borders around prominent interactive elements in a dark context.

borderBrandAccentUsed for borders around branded elements.

borderBrandAccentLargeUsed for large borders around branded elements.

borderBrandAccentLightUsed for borders around branded elements in a dark context.

borderBrandAccentLightLargeUsed for large borders around branded elements in a dark context.

borderPositiveUsed for borders around “positive” elements.

borderPositiveLightUsed for borders around “positiveLight” elements.

borderCriticalUsed for borders around “critical” elements.

borderCriticalLargeUsed for large borders around “critical” elements.

borderCriticalLightUsed for borders around “criticalLight” elements.

borderCriticalLightLargeUsed for large borders around “criticalLight” elements.

borderCautionUsed for borders around “caution” elements.

borderCautionLightUsed for borders around “cautionLight” elements.

borderInfoUsed for borders around “info” elements.

borderInfoLightUsed for borders around “infoLight” elements.

borderPromoteUsed for borders around “promote” elements.

borderPromoteLightUsed for borders around “promoteLight” elements.