metamask-extension/ui/components/ui/box

import { Story, Canvas, ArgsTable } from '@storybook/addon-docs';

import ActionableMessage from '../actionable-message';

import Box from '.';

# Box

Box is a utility component that can be used for layout or as a base for other UI components.

<Canvas>
  <Story id="ui-components-ui-box-box-stories-js--default-story" />
</Canvas>

## Props

| Name            | Description                                                                                                                                                                                                                           | Default            |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
| children        | The children of the Box component. If `function` type will render the child as the Box node instead of a child of the Box                                                                                                             | -                  |
| className       | Additional className of the Box component                                                                                                                                                                                             | -                  |
| margin          | 0, 1, 2, 4, 6, 8, 9, 10, 12, 'auto' or array of values [1, 2, 'auto'] for responsive props                                                                                                                                            | -                  |
| marginTop       | 0, 1, 2, 4, 6, 8, 9, 10, 12, 'auto' or array of values for responsive props                                                                                                                                                           | -                  |
| marginBottom    | 0, 1, 2, 4, 6, 8, 9, 10, 12, 'auto' or array of values for responsive props                                                                                                                                                           | -                  |
| marginRight     | 0, 1, 2, 4, 6, 8, 9, 10, 12, 'auto' or array of values for responsive props                                                                                                                                                           | -                  |
| marginLeft      | 0, 1, 2, 4, 6, 8, 9, 10, 12, 'auto' or array of values for responsive props                                                                                                                                                           | -                  |
| padding         | 0, 1, 2, 4, 6, 8, 9, 10, 12 or array of numbers [1, 2] for responsive props                                                                                                                                                           | -                  |
| paddingTop      | 0, 1, 2, 4, 6, 8, 9, 10, 12 or array of numbers [1, 2] for responsive props                                                                                                                                                           | -                  |
| paddingBottom   | 0, 1, 2, 4, 6, 8, 9, 10, 12 or array of numbers [1, 2] for responsive props                                                                                                                                                           | -                  |
| paddingRight    | 0, 1, 2, 4, 6, 8, 9, 10, 12 or array of numbers [1, 2] for responsive props                                                                                                                                                           | -                  |
| paddingLeft     | 0, 1, 2, 4, 6, 8, 9, 10, 12 or array of numbers [1, 2] for responsive props                                                                                                                                                           | -                  |
| display         | DISPLAY values or array of DISPLAY values for responsive props from [../ui/helpers/constants/design-system.js](https://github.com/MetaMask/metamask-extension/blob/develop/ui/helpers/constants/design-system.js)                     | -                  |
| flexDirection   | FLEX_DIRECTION values or array of FLEX_DIRECTION values for responsive props from [../ui/helpers/constants/design-system.js](https://github.com/MetaMask/metamask-extension/blob/develop/ui/helpers/constants/design-system.js)       | FLEX_DIRECTION.ROW |
| flexWrap        | FLEX_WRAP values or array of FLEX_WRAP values for responsive props from [../ui/helpers/constants/design-system.js](https://github.com/MetaMask/metamask-extension/blob/develop/ui/helpers/constants/design-system.js)                 | -                  |
| alignItems      | ALIGN_ITEMS values or array of ALIGN_ITEMS values for responsive props from [../ui/helpers/constants/design-system.js](https://github.com/MetaMask/metamask-extension/blob/develop/ui/helpers/constants/design-system.js)             | -                  |
| justifyContent  | JUSTIFY_CONTENT values or array of JUSTIFY_CONTENT values from [../ui/helpers/constants/design-system.js](https://github.com/MetaMask/metamask-extension/blob/develop/ui/helpers/constants/design-system.js)                          | -                  |
| gap             | 0, 1, 2, 4, 6, 8, 9, 10, 12 or array of numbers [1, 2] for responsive props                                                                                                                                                           | -                  |
| textAlign       | TEXT_ALIGN values or array of TEXT_ALIGN values for responsive props from [../ui/helpers/constants/design-system.js](https://github.com/MetaMask/metamask-extension/blob/develop/ui/helpers/constants/design-system.js)               | -                  |
| width           | BLOCK_SIZES values or array of BLOCK_SIZES values for responsive props from [../ui/helpers/constants/design-system.js](https://github.com/MetaMask/metamask-extension/blob/develop/ui/helpers/constants/design-system.js)             | -                  |
| height          | BLOCK_SIZES values or array of BLOCK_SIZES values for responsive props [../ui/helpers/constants/design-system.js](https://github.com/MetaMask/metamask-extension/blob/develop/ui/helpers/constants/design-system.js)                  | -                  |
| color           | COLORS values or array of COLORS values for responsive props [../ui/helpers/constants/design-system.js](https://github.com/MetaMask/metamask-extension/blob/develop/ui/helpers/constants/design-system.js)                            | -                  |
| backgroundColor | BACKGROUND_COLORS values or array of BACKGROUND_COLORS values for responsive props from [../ui/helpers/constants/design-system.js](https://github.com/MetaMask/metamask-extension/blob/develop/ui/helpers/constants/design-system.js) | -                  |
| borderColor     | BORDER_COLORS values or array of BORDER_COLORS values for responsive props from [../ui/helpers/constants/design-system.js](https://github.com/MetaMask/metamask-extension/blob/develop/ui/helpers/constants/design-system.js)         | -                  |
| borderWidth     | 0, 1, 2, 4, 6, 8, 9, 10, 12 or array of numbers [1, 2] for responsive props                                                                                                                                                           | -                  |
| borderRadius    | BORDER_RADIUS values or array of BORDER_RADIUS values for responsive props from [../ui/helpers/constants/design-system.js](https://github.com/MetaMask/metamask-extension/blob/develop/ui/helpers/constants/design-system.js)         | -                  |
| borderStyle     | BORDER_STYLE values or array of BORDER_STYLE values for responsive props from [../ui/helpers/constants/design-system.js](https://github.com/MetaMask/metamask-extension/blob/develop/ui/helpers/constants/design-system.js)           | -                  |
| as              | The polymorphic `as` prop allows you to change the root HTML element of the Box component. Defaults to 'div'                                                                                                                          | 'div'              |

## Usage

The following describes the props and example usage for this component.

### Margin

The margin props `margin`, `marginTop`, `marginRight`, `marginBottom`, and `marginLeft` can be used to set the margins of the `Box` component. All of the margin props accept [responsive props](#responsive-props) in the form of array props

Accepted props are: `0, 1, 2, 4, 6, 8, 9, 10, 12, 'auto` or array of these values

<Canvas>
  <Story id="ui-components-ui-box-box-stories-js--margin" />
</Canvas>

```jsx
<Box margin={4} />
<Box marginTop={4} />
<Box marginRight={4} />
<Box marginBottom={4} />
<Box marginLeft={'auto'} />

// Responsive props
<Box margin={[4, 8]} />
<Box marginTop={[4, 8]} />
<Box marginRight={[4, 8]} />
<Box marginBottom={[4, 8]} />
<Box marginLeft={['auto', 8]} />
```

### Padding

The padding props work very similarly to margin. The padding props `padding`, `paddingTop`, `paddingRight`, `paddingBottom`, and `paddingLeft` can be used to set the paddings of the `Box` component. All of the padding props accept [responsive props](#responsive-props) in the form of array props

Accepted props are: `0, 1, 2, 4, 6, 8, 9, 10, 12` or array of these values

<Canvas>
  <Story id="ui-components-ui-box-box-stories-js--padding" />
</Canvas>

```jsx
<Box padding={4} />
<Box paddingTop={4} />
<Box paddingRight={4} />
<Box paddingBottom={4} />
<Box paddingLeft={4} />

// Responsive props
<Box padding={[4, 8]} />
<Box paddingTop={[4, 8]} />
<Box paddingRight={[4, 8]} />
<Box paddingBottom={[4, 8]} />
<Box paddingLeft={[4, 8]} />
```

### Display

The `display` prop can be used to set the display of the `Box` component. All of the display props accept [responsive props](#responsive-props) in the form of array props.

Accepted props imported from the design system `DISPLAY` const are:

- `DISPLAY.BLOCK`
- `DISPLAY.FLEX`
- `DISPLAY.GRID`
- `DISPLAY.INLINE_BLOCK`
- `DISPLAY.INLINE_FLEX`
- `DISPLAY.INLINE_GRID`
- `DISPLAY.INLINE`
- `DISPLAY.LIST_ITEM`
- `DISPLAY.NONE`

or array of these values.

```jsx
import { DISPLAY } from '../../../helpers/constants/design-system';
import Box from '../ui/box';

<Box display={DISPLAY.BLOCK} />
<Box display={DISPLAY.FLEX} />
<Box display={DISPLAY.GRID} />
<Box display={DISPLAY.INLINE_BLOCK} />
<Box display={DISPLAY.INLINE_FLEX} />
<Box display={DISPLAY.INLINE} />
<Box display={DISPLAY.NONE} />
```

### Color

The `color` prop can be used to set the color of the content in Box component. The `color` prop accepts [responsive props](#responsive-props) in the form of array props. Defaults to `COLORS.TEXT_DEFAULT`

<Canvas>
  <Story id="ui-components-ui-box-box-stories-js--color" />
</Canvas>

Example of importing `COLORS` object with `Box` component

```jsx
import { COLORS } from '../../../helpers/constants/design-system';
import Box from '../ui/box';

<Box color={COLORS.TEXT_DEFAULT}>Text goes here</Box>;
```

### Background Color

Use the `backgroundColor` prop along with the `COLORS` object from `ui/helpers/constants/design-system.js` to change background color. The `backgroundColor` prop accepts [responsive props](#responsive-props) in the form of array props.

<Canvas>
  <Story id="ui-components-ui-box-box-stories-js--background-color" />
</Canvas>

Example of importing `COLORS` object with `Box` component

```jsx
import { COLORS } from '../../../helpers/constants/design-system';
import Box from '../ui/box';

<Box backgroundColor={COLORS.BACKGROUND_DEFAULT}>
  <Typography color={COLORS.TEXT_DEFAULT}>COLORS.BACKGROUND_DEFAULT</Typography>
</Box>;
```

### Border Color

Use the `borderColor` prop along with the `COLORS` object from `ui/helpers/constants/design-system.js` to change border color. The `borderColor` prop accepts [responsive props](#responsive-props) in the form of array props.

<Canvas>
  <Story id="ui-components-ui-box-box-stories-js--border-color" />
</Canvas>

Example of importing `COLORS` object with `Box` component

```jsx
import { COLORS } from '../../../helpers/constants/design-system';
import Box from '../ui/box';

<Box
  backgroundColor={COLORS.BACKGROUND_DEFAULT}
  borderColor={COLORS.BORDER_DEFAULT}
>
  <Typography color={COLORS.TEXT_DEFAULT}>COLORS.BORDER_DEFAULT</Typography>
</Box>;
```

### Border Radius

Use the `borderRadius` prop along with the `BORDER_RADIUS` object from `ui/helpers/constants/design-system.js` to change border radius. The `borderRadius` prop accepts [responsive props](#responsive-props) in the form of array props.

<Canvas>
  <Story id="ui-components-ui-box-box-stories-js--border-radius" />
</Canvas>

Example of importing `BORDER_RADIUS` object with `Box` component

```jsx
import { BORDER_RADIUS } from '../../../helpers/constants/design-system';
import Box from '../ui/box';

<Box borderRadius={BORDER_RADIUS.NONE}>BORDER_RADIUS.NONE 0px</Box>
<Box borderRadius={BORDER_RADIUS.XS}>BORDER_RADIUS.XS 2px</Box>
<Box borderRadius={BORDER_RADIUS.SM}>BORDER_RADIUS.SM 4px</Box>
<Box borderRadius={BORDER_RADIUS.MD}>BORDER_RADIUS.MD 6px</Box>
<Box borderRadius={BORDER_RADIUS.LG}>BORDER_RADIUS.LG 8px</Box>
<Box borderRadius={BORDER_RADIUS.XL}>BORDER_RADIUS.XL 12px</Box>
<Box borderRadius={BORDER_RADIUS.PILL}>BORDER_RADIUS.PILL 9999px</Box>
```

### Responsive Props

The box component provides a responsive props api in the form of array props. Array props are inspired by [styled-systems array props](https://styled-system.com/guides/array-props). The responsive props follow a mobile first methodology with the first item in the array applying the style to the base level size e.g. `0px` and up. The second item overwrites the first items styles at the next breakpoint.

- All Box props accept the responsive props format
- To skip a breakpoint use `null` as the skipped item's value e.g. `<Box display={['display', null, ;flex']} />`

```
// the responsive props
<Box display={['block', 'flex']} />

// is equivalent to the css
.box {
  display: block;

  @media screen and (max-width: $breakpoint-sm) {
    display: flex;
  }
}
```

<Canvas>
  <Story id="ui-components-ui-box-box-stories-js--responsive-props" />
</Canvas>

```jsx
import { COLORS } from '../../../helpers/constants/design-system';
import Box from '../ui/box';

<Box
  padding={[2, 4]}
  gap={[2, 4]}
  display={['flex']}
  flexDirection={['column', 'row']}
  borderColor={COLORS.BORDER_DEFAULT}
>
  <Box
    padding={[4, 8]}
    backgroundColor={COLORS.BACKGROUND_ALTERNATIVE}
    borderColor={COLORS.BORDER_MUTED}
  >
    responsive
  </Box>
  <Box
    padding={[4, 8]}
    backgroundColor={COLORS.BACKGROUND_ALTERNATIVE}
    borderColor={COLORS.BORDER_MUTED}
  >
    props
  </Box>
  <Box
    padding={[4, 8]}
    backgroundColor={COLORS.BACKGROUND_ALTERNATIVE}
    borderColor={COLORS.BORDER_MUTED}
  >
    example
  </Box>
</Box>;
```

### As

The polymorphic `as` prop allows you to change the root HTML element of the Box component. Defaults to `'div'`

<Canvas>
  <Story id="ui-components-ui-box-box-stories-js--as" />
</Canvas>

```jsx
import Box from '../../ui/box';

<Box>div(default)</Box>
<Box as="ul">ul</Box>
<Box as="li">li</Box>
<Box as="button">button</Box>
<Box as="header">header</Box>
```