---
title: Box
description: Use a box to simplify the process of applying one-off styles to an element
keywords: ['layout']
ready: true
source: https://github.com/primer/brand/blob/main/packages/react/src/Box/Box.tsx
storybook: '/brand/storybook/?path=/story/components-box--default'
---

```js
import {Box} from '@primer/react-brand'
```

## Examples

Box requires the `dir` attribute to be set on the `<html />` element to ensure that directional padding and margin values are applied correctly.

### Default

The `Box` component, by default, represents an empty `<div>` element with no predefined styles applied to it.

```jsx
<Box>With GitHub Copilot, you’re always in charge.</Box>
```

### Uniform padding

Use `padding` to apply equal inner spacing to all sides of an element.

```jsx
<>
  <Stack direction="horizontal" alignItems="center" flexWrap="wrap">
    <Box padding="condensed" className="bg-red-lines">
      condensed
    </Box>
    <Box padding="normal" className="bg-red-lines">
      normal
    </Box>
    <Box padding="spacious" className="bg-red-lines">
      spacious
    </Box>
  </Stack>
  <Stack direction="horizontal" alignItems="center" flexWrap="wrap">
    <Box padding={24} className="bg-red-lines">
      24
    </Box>
    <Box padding={32} className="bg-red-lines">
      32
    </Box>
    <Box padding={48} className="bg-red-lines">
      48
    </Box>
    <Box padding={64} className="bg-red-lines">
      64
    </Box>
    <Box padding={96} className="bg-red-lines">
      96
    </Box>
  </Stack>
</>
```

### Directional padding

Apply internal spacing to a specific side. Directional padding is implemented with CSS logical properties and accepts functional spacing names, or values from the base scale.

```jsx
<Stack direction="horizontal" alignItems="center" flexWrap="wrap">
  <Box paddingBlockStart={64} className="bg-red-lines">
    block start
  </Box>
  <Box paddingInlineEnd={64} className="bg-red-lines">
    inline end
  </Box>
  <Box paddingBlockEnd={64} className="bg-red-lines">
    block end
  </Box>
  <Box paddingInlineStart={64} className="bg-red-lines">
    inline start
  </Box>
</Stack>
```

### Uniform margin

Use `margin` to apply equal outer spacing to all sides of an element.

```jsx
<>
  <Stack direction="horizontal" alignItems="center" flexWrap="wrap">
    <Box className="bg-yellow-lines">
      <Box margin="condensed" className="bg-red-lines">
        condensed
      </Box>
    </Box>
    <Box className="bg-yellow-lines">
      <Box margin="normal" className="bg-red-lines">
        normal
      </Box>
    </Box>
    <Box className="bg-yellow-lines">
      <Box margin="spacious" className="bg-red-lines">
        spacious
      </Box>
    </Box>
  </Stack>
  <Stack direction="horizontal" alignItems="center" flexWrap="wrap">
    <Box className="bg-yellow-lines">
      <Box margin={24} className="bg-red-lines">
        24
      </Box>
    </Box>
    <Box className="bg-yellow-lines">
      <Box margin={32} className="bg-red-lines">
        32
      </Box>
    </Box>
    <Box className="bg-yellow-lines">
      <Box margin={48} className="bg-red-lines">
        48
      </Box>
    </Box>
    <Box className="bg-yellow-lines">
      <Box margin={64} className="bg-red-lines">
        64
      </Box>
    </Box>
    <Box className="bg-yellow-lines">
      <Box margin={96} className="bg-red-lines">
        96
      </Box>
    </Box>
  </Stack>
</>
```

### Directional margin

Apply external spacing to a specific side. Directional margins are implemented with CSS logical properties and accepts functional spacing names, or values from the base scale.

```jsx
<Stack direction="horizontal" alignItems="center" flexWrap="wrap">
  <Box className="bg-yellow-lines">
    <Box marginBlockStart={64} className="bg-red-lines">
      block start
    </Box>
  </Box>
  <Box className="bg-yellow-lines">
    <Box marginInlineEnd={64} className="bg-red-lines">
      inline end
    </Box>
  </Box>
  <Box className="bg-yellow-lines">
    <Box marginBlockEnd={64} className="bg-red-lines">
      block end
    </Box>
  </Box>
  <Box className="bg-yellow-lines">
    <Box marginInlineStart={64} className="bg-red-lines">
      inline start
    </Box>
  </Box>
</Stack>
```

### Responsive spacing

All padding and margin options can be configured for indivisual viewports: Each viewport entry is applied using a `min-width` media query.

```jsx
<Stack direction="horizontal" alignItems="center" flexWrap="wrap">
  <Box className="bg-yellow-lines">
    <Box
      margin={{
        narrow: 48,
        regular: 96,
        wide: 128,
      }}
      className="bg-red-lines"
    >
      margin
    </Box>
  </Box>
  <Box
    padding={{
      narrow: 48,
      regular: 96,
      wide: 128,
    }}
    className="bg-red-lines"
  >
    padding
  </Box>
</Stack>
```

### Border radius

```jsx
<Stack direction="horizontal" flexWrap="wrap">
  <Box borderRadius="small" padding="spacious" className="bg-red-lines">
    small
  </Box>
  <Box borderRadius="medium" padding="spacious" className="bg-red-lines">
    medium
  </Box>
  <Box borderRadius="large" padding="spacious" className="bg-red-lines">
    large
  </Box>
  <Box borderRadius="full" padding="spacious" className="bg-red-lines">
    full
  </Box>
</Stack>
```

### Borders

```jsx
<Stack direction="horizontal" flexWrap="wrap">
  <Box backgroundColor="subtle" borderWidth="thin" borderColor="default" borderStyle="solid" padding="spacious">
    thin
  </Box>
  <Box backgroundColor="subtle" borderWidth="thick" borderColor="default" borderStyle="solid" padding="spacious">
    thick
  </Box>
  <Box backgroundColor="subtle" borderWidth="thicker" borderColor="default" borderStyle="solid" padding="spacious">
    thicker
  </Box>
</Stack>
```

### Background colors

```jsx
<Stack direction="horizontal" flexWrap="wrap">
  <Box backgroundColor="default" borderWidth="thin" borderColor="default" borderStyle="solid" padding="spacious">
    default
  </Box>
  <Box backgroundColor="subtle" borderWidth="thin" borderColor="default" borderStyle="solid" padding="spacious">
    subtle
  </Box>
  <Box backgroundColor="inset" borderWidth="thin" borderColor="default" borderStyle="solid" padding="spacious">
    inset
  </Box>
  <Box backgroundColor="overlay" borderWidth="thin" borderColor="default" borderStyle="solid" padding="spacious">
    overlay
  </Box>
  <Box
    backgroundColor="var(--base-color-scale-green-5)"
    borderWidth="thin"
    borderColor="default"
    borderStyle="solid"
    padding="spacious"
  >
    Custom
  </Box>
</Stack>
```

## Component props

### Box

| Name                     | Type                     |   Default   | Description                                                                 |
| :----------------------- | :----------------------- | :---------: | :-------------------------------------------------------------------------- |
| `padding`                | `BoxSpacingValues`       | `undefined` | Adds padding to all internal sides of the Box.                              |
| `paddingBlockStart`      | `BoxSpacingValues`       | `undefined` | Adds padding to the internal block start (top) side of the Box.             |
| `paddingRight`           | `BoxSpacingValues`       | `undefined` | Adds padding to the internal inline end (right) of the Box.                 |
| `paddingBlockEnd`        | `BoxSpacingValues`       | `undefined` | Adds padding to the internal block end (bottom) side of the Box.            |
| `paddingLeft`            | `BoxSpacingValues`       | `undefined` | Adds padding to the internal inline start (left) side of the Box.           |
| `margin`                 | `BoxSpacingValues`       | `undefined` | Adds margin to all external sides of the Box.                               |
| `marginBlockStart`       | `BoxSpacingValues`       | `undefined` | Adds margin to the external block start (top) side of the Box.              |
| `marginInlineEnd`        | `BoxSpacingValues`       | `undefined` | Adds margin to the external inline end (right) side of the Box.             |
| `marginBlockEnd`         | `BoxSpacingValues`       | `undefined` | Adds margin to the external block end (bottom) side of the Box.             |
| `marginInlineStart`      | `BoxSpacingValues`       | `undefined` | Adds margin to the external inline start (left) side of the Box.            |
| `backgroundColor`        |                          | `undefined` | Applies a system-level background color to the Box.                         |
| `borderRadius`           | `BoxBorderRadiusOptions` | `undefined` | Applies a system-level border radius value to the Box.                      |
| `borderWidth`            | `BoxBorderWidthOptions`  | `undefined` | Applies a system-level border width value to the Box.                       |
| `borderBlockStartWidth`  | `BoxBorderWidthOptions`  | `undefined` | Applies a system-level border width value to block-start side of the Box.   |
| `borderInlineEndWidth`   | `BoxBorderWidthOptions`  | `undefined` | Applies a system-level border width value to inline-end side of the Box.    |
| `borderBlockEndWidth`    | `BoxBorderWidthOptions`  | `undefined` | Applies a system-level border width value to block-end side of the Box.     |
| `borderInlineStartWidth` | `BoxBorderWidthOptions`  | `undefined` | Applies a system-level border width value to inline-start side of the Box.  |
| `borderColor`            | `BoxBorderColorOptions`  | `undefined` | Applies a system-level border color value to the Box.                       |
| `borderStyle`            |                          | `undefined` | Applies border style. Values correspond to the CSS `border-style` property. |
