Design System
v5.3.0
⌘K

Box

Mobile Support: Full
Jump to Props

Group sections of content and easily adjust position, spacing and size

On this page

Import

import { Box } from "@vitality-ds/components";

Usage

The Box component is useful for adding ad-hoc padding, margin, width and height properties (non exhaustive). The box is not for changing colours and visual styles, just layouts. This means you don't need to created a new styled() component every time you need to tweak the layout.

() => {
  const DecorativeBox = () => <DocsFlex>Content</DocsFlex>;
  return (
    <DocsBox css={{ backgroundColor: "$neutral2", border: "1px solid $neutral6"}}>
      <Box padding="lg" margin="sm" width={300} height={100}>
        <FauxBadge>One</FauxBadge>
        <FauxBadge>Two</FauxBadge>
      </Box>
      <Box padding="lg" margin="lg" width={200} height={100}>
        <FauxBadge>Three</FauxBadge>
        <FauxBadge>Four</FauxBadge>
      </DocsBox>
    </div>
  );
};

Padding

Padding can be set using padding, px, py, pt, pb, pl and pr. You can pass any valid value in the Vitality space scale or none for a zero value.

() => {
  return (
    <div
      style={{
        backgroundColor: "var(--vitality-colors-neutral12)",
        boxSizing: "border-box",
      }}
    >
      <Box padding="lg" pl="sm">
        <FauxBadge>Item</FauxBadge>
      </Box>
    </div>
  );
};

Margin

Margin can be set using margin, mx, my, mt, mb, ml and mr. You can pass any valid value in the Vitality space scale or none for a zero value.

() => {
  return (
    <div
      style={{
        backgroundColor: "var(--vitality-colors-neutral12)",
        boxSizing: "border-box",
      }}
    >
      <Box margin="lg" ml="sm">
        <FauxBadge>Item</FauxBadge>
      </Box>
    </div>
  );
};

Width

In most cases, you should not need to set an explicit width on an element. Usually the parent component should specify the width based on flex or grid properties, or the Box element's children would dictate the width. In cases where you do need to enforce a width, simply pass any valid CSS value to the width property.

() => {
  return (
    <div
      style={{
        backgroundColor: "var(--vitality-colors-neutral12)",
        boxSizing: "border-box",
        width: "100%",
      }}
    >
      <Box width="50%">
        <FauxBadge>Item</FauxBadge>
      </Box>
    </div>
  );
};

maxWidth

() => {
  return (
    <div
      style={{
        backgroundColor: "var(--vitality-colors-neutral12)",
        boxSizing: "border-box",
        width: "100%",
      }}
    >
      <Box maxWidth={200}>
        <FauxBadge>Item</FauxBadge>
      </Box>
    </div>
  );
};

minWidth

() => {
  return (
    <div
      style={{
        backgroundColor: "var(--vitality-colors-neutral12)",
        boxSizing: "border-box",
        width: "20%",
        padding: "32px",
      }}
    >
      <Box minWidth={200}>
        <FauxBadge>Item</FauxBadge>
      </Box>
    </div>
  );
};

Height

() => {
  return (
    <div
      style={{
        backgroundColor: "var(--vitality-colors-neutral12)",
        boxSizing: "border-box",
      }}
    >
      <Box height={100}>
        <FauxBadge>Item</FauxBadge>
      </Box>
    </div>
  );
};

maxHeight

The below example shows how the invisible container around the items is not exceeding 10 pixels height.

() => {
  return (
    <div
      style={{
        backgroundColor: "var(--vitality-colors-neutral12)",
        boxSizing: "border-box",
        width: "100%",
        height: "100%",
        padding: 32,
      }}
    >
      <Box maxHeight={10}>
        <FauxBadge>Item</FauxBadge>
        <FauxBadge>Item</FauxBadge>
      </Box>
    </div>
  );
};

minHeight

The below example shows how the invisible container around the items is no less than 100 pixels height.

() => {
  return (
    <div
      style={{
        backgroundColor: "var(--vitality-colors-neutral12)",
        boxSizing: "border-box",
        height: 80,
        padding: "32px",
      }}
    >
      <Box minHeight={100}>
        <FauxBadge>Item</FauxBadge>
        <FauxBadge>Item</FauxBadge>
        <FauxBadge>Item</FauxBadge>
      </Box>
    </div>
  );
};

Growing and Shrinking in Flex environments

When the Box component is used within a display="flex" container (or using the Flex component), you can control whether it should grow/shrink.

  • shouldShrink is true by default, meaning most elements will try to shrink in order to fit others
  • shouldGrow is false by default, meaning most elements will not attempt to grow beyond what their content requires.

These defaults are based on the default CSS values for the flex-shrink and flex-grow properties.

If you require fine-granular control over an element's flex properties, consider creating your own styled() components.

Prevent Shrinking

<DocsFlex
  style={{
    direction: "row",
    width: "100%",
    spacing: "xl",
    wrap: "noWrap",
  }}
>
  <Box shouldShrink={false}>
    <FauxBadge>
      This element will avoid shrinking despite the other element attempting to
      grow.
    </FauxBadge>
  </Box>
  <Box>
    <Typography>
      This element will attempt to grow because of the size of its content.
    </Typography>
  </Box>
</DocsFlex>

Enforce Growing

This example demonstrates how you can "enforce" a Box to grow despite its contents not intrinsicly requiring its growth.

<DocsFlex
  style={{
    direction: "row",
    width: "100%",
    spacing: "lg",
    justify: "between",
    align: "center",
  }}
>
  <Box shouldGrow>
    <Button shouldFitContainer>Click here</Button>
  </Box>
  <Box width={200}>
    <FauxBadge>
      This element will try to grow but cannot because the other element is
      forced to grow.
    </FauxBadge>
  </Box>
</DocsFlex>

Positioning

You can set the CSS position property on any Box component as well as pass any valid CSS value to the top, bottom, left, right and inset properties.

<DocsFlex
  style={{
    backgroundColor: "var(--vitality-colors-neutral12)",
    width: "100%",
    height: 200,
  }}
>
  <Box position="relative" width="100%" height="100%">
    <Box position="absolute" bottom={6} right="20%" width={200}>
      <FauxBadge>Element</FauxBadge>
    </Box>
  </Box>
</DocsFlex>

Figma Library

Figma.logo

Props

bottom

Type

Bottom

children

Description

The content of the box

Type

ReactNode

gridSpans

Description

When used in a CSS grid, control the gridColumn` and `gridRow property. Takes any valid value passed to these CSS properties.

Type

{ cols?: GridColumn; rows?: GridRow; }

height

Type

Height

htmlTag

Type

string

inset

Type

Inset

left

Type

Left

margin

Type

SpaceKeys

maxHeight

Type

MaxHeight

maxWidth

Type

MaxWidth

mb

Type

SpaceKeys

minHeight

Type

MinHeight

minWidth

Type

MinWidth

ml

Type

SpaceKeys

mr

Type

SpaceKeys

mt

Type

SpaceKeys

mx

Type

SpaceKeys

my

Type

SpaceKeys

padding

Type

SpaceKeys

pb

Type

SpaceKeys

pl

Type

SpaceKeys

position

Type

"fixed" | "absolute" | "relative" | "static" | "sticky"

pr

Type

SpaceKeys

pt

Type

SpaceKeys

px

Type

SpaceKeys

py

Type

SpaceKeys

right

Type

Right

shouldGrow

Type

boolean

shouldShrink

Type

boolean

Default Value

top

Type

Top

width

Type

Width

© 2025