# Box

> **WARNING:** The Box component is currently in Alpha status and breaking changes may occur

A box is a generic way to add structure to your page. Stop reaching for CSS
Modules to perform basic page layout, and instead use the Box component.

## Design & usage guidelines

A Box is useful for wrapping content with a specific HTML5 element, and with
common Atlantis specific CSS styles. Box supports standard alignment, border,
borderColor, borderRadius, direction, gap, height, justification, margin,
overflow, padding, position, width and whitespace options.

Use Box if your wrapping CSS styles can be achieved with a prop configuration of
the Box component, to avoid the need for creating a CSS module. Some basic
examples are below, all configuration options are provided in the Basic Web
example via the left-hand navigation.

## Related components

[Card](../Card/Card.md) is a more opionated layout container, with a set
background, border, radius, and an optional preset header. It is the preferred
way to group related information and tasks so that users can consistently scan
and prioritize information more easily.

### No Props

```tsx
import React from "react";
import { Box } from "@jobber/components/Box";

export function BoxNoPropsExample() {
  return (
    <Box>
      This is Box without props. It marks your content as display: flex and
      flex-direction: column
    </Box>
  );
}
```

### Border Base and Padding Base

```tsx
import React from "react";
import { Box } from "@jobber/components/Box";

export function BoxBorderBasePaddingBaseExample() {
  return (
    <Box border="base" padding="base">
      By default you get no padding or borders, but with two &apos;base&apos;
      props you can have both.
    </Box>
  );
}
```

### Border Thick and Padding Large

```tsx
import React from "react";
import { Box } from "@jobber/components/Box";

export function BoxBorderThickPaddingLargeExample() {
  return (
    <Box border="thick" padding="large">
      Standard paddings and margins are available, and different borders. This
      is using the &apos;thick&apos; border along with padding &apos;large&apos;
    </Box>
  );
}
```

### Border Thickest and Margin Largest and Padding Extravagant

```tsx
import React from "react";
import { Box } from "@jobber/components/Box";

export function BoxBorderThickestMarginLargestExample() {
  return (
    <Box margin="largest" border="thickest" padding="extravagant">
      Want a big margin and huge padding? Box has those too.
    </Box>
  );
}
```

## What about actual layout usages?

If you don't really want borders around everything but just want to lay out some
content on the page? You can do that too.

```tsx
import React from "react";
import { Box } from "@jobber/components/Box";

export function BoxLayoutRowExample() {
  return (
    <Box direction="row">
      <Box padding="base" width="grow">
        Left
      </Box>
      <Box padding="base" width="grow">
        Right
      </Box>
    </Box>
  );
}
```

### Maybe some custom heights or widths?

Box has those as well.

```tsx
import React from "react";
import { Box } from "@jobber/components/Box";

export function BoxCustomHeightsWidthsExample() {
  return (
    <Box direction="row" alignItems="center">
      <Box padding="base" width={350} border="base">
        Left, 350px wide
      </Box>
      <Box padding="base" height={75} border="base">
        Right, 75px high
      </Box>
    </Box>
  );
}
```

### What about a gap between elements?

Standard sizes are supported.

```tsx
import React from "react";
import { Box } from "@jobber/components/Box";

export function BoxGapExample() {
  return (
    <Box direction="row" alignItems="center" gap="large">
      <Box padding="base" width={50} border="base">
        Left, 50px wide
      </Box>
      <Box padding="base" height={25} border="base">
        Right, 25px high
      </Box>
    </Box>
  );
}
```

### I have specific border-left and margin-bottom requirements.

Box supports objects for some of its props, including padding and margin
"bottom, horizontal, left, right, top, vertical"

```tsx
import React from "react";
import { Box } from "@jobber/components/Box";

export function BoxSpecificBorder1Example() {
  return (
    <Box padding={{ top: "large" }} border="thick">
      Top Padding?
    </Box>
  );
}
```

```tsx
import React from "react";
import { Box } from "@jobber/components/Box";

export function BoxSpecificBorder2Example() {
  return (
    <Box margin={{ left: "large" }} border="base" padding="base">
      Left Margin?
    </Box>
  );
}
```


## Developer notes

A key consideration of the Alpha status of this component is whether it should
restrict any non-semantic color usage. It was faster to roll this component with
the full colour set for now.

We will remove the Alpha status when we finalize the decision on the API for
color usage and how we might allow for flexibility while ensuring the component
defaults to respecting theme/modes.


## Props

### Web

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `alignItems` | `AlignItems` | No | — | This feature is well established and works across many devices and browser versions. It’s been available across brows... |
| `alignSelf` | `AlignSelf` | No | — | This feature is well established and works across many devices and browser versions. It’s been available across brows... |
| `as` | `"article" | "aside" | "div" | "main" | "section" | "span"` | No | `div` |  |
| `background` | `"disabled" | "icon" | "event" | "invoice" | "job" | "quote" | "request" | "task" | "text" | "visit" | "warning" | "success" | "base-grey--100" | "base-grey--200" | "base-grey--300" | ... 275 more ... | "client--onSurface"` | No | — |  |
| `border` | `"base" | "thick" | "thicker" | "thickest" | BoxBorderWidth` | No | — |  |
| `borderColor` | `"disabled" | "icon" | "event" | "invoice" | "job" | "quote" | "request" | "task" | "text" | "visit" | "warning" | "success" | "base-grey--100" | "base-grey--200" | "base-grey--300" | ... 275 more ... | "client--onSurface"` | No | — |  |
| `direction` | `FlexDirection` | No | — |  |
| `gap` | `"base" | "extravagant" | "large" | "larger" | "largest" | "minuscule" | "slim" | "small" | "smaller" | "smallest"` | No | — |  |
| `height` | `BoxDimension` | No | `auto` |  |
| `justifyContent` | `JustifyContent` | No | — | This feature is well established and works across many devices and browser versions. It’s been available across brows... |
| `margin` | `"base" | "extravagant" | "large" | "larger" | "largest" | "minuscule" | "slim" | "small" | "smaller" | "smallest" | BoxSpace` | No | — |  |
| `overflow` | `Overflow` | No | — | This feature is well established and works across many devices and browser versions. It’s been available across brows... |
| `padding` | `"base" | "extravagant" | "large" | "larger" | "largest" | "minuscule" | "slim" | "small" | "smaller" | "smallest" | BoxSpace` | No | — |  |
| `position` | `Position` | No | `relative` | This feature is well established and works across many devices and browser versions. It’s been available across brows... |
| `preserveWhiteSpace` | `boolean` | No | — |  |
| `radius` | `"base" | "circle" | "large" | "larger" | "small"` | No | — |  |
| `tabIndex` | `number` | No | — | [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLElement/tabIndex) |
| `width` | `BoxDimension` | No | `auto` |  |