# dds-box



<!-- Auto Generated Below -->


## Overview

A surface primitive: a block container with token-scaled padding, background, border and radius, and no layout opinion of its own. It is a generic container to assistive technology; set `role` and `aria-*` on the host where the content has meaning.

## Usage

### Box

#### A padded surface

A box is a surface with no layout of its own. Set `padding` to space its content from the edge, `background` to pick a step on the surface scale, and `border` and `radius` to outline it.

```html
<dds-box padding="m" background="2" border="s" radius="container">
  <p>Quarterly summary for all markets.</p>
</dds-box>
```

#### Surface and layout

A box never arranges its children, so put a `dds-stack` inside it to lay them out. Nest them the other way round to give one item of a stack its own surface.

```html
<dds-box padding="l" background="2" border="s" radius="container">
  <dds-stack gap="s">
    <h3>Campaign overview</h3>
    <p>Performance summary for Q1 media activations.</p>
    <dds-button>View report</dds-button>
  </dds-stack>
</dds-box>
```

#### Padding per axis

`padding` applies to both axes. `paddingBlock` and `paddingInline` override it for one axis each.

```html
<dds-box padding="s" padding-inline="xl" background="3">
  <p>Narrow vertically, wide horizontally.</p>
</dds-box>
```

#### Borders

`border` sets the width and is always solid. `borderColor` takes a step on the border scale and has no effect while `border` is `none`.

```html
<dds-box padding="m" border="m" border-color="6" radius="element">
  <p>A heavier, darker outline.</p>
</dds-box>
```

#### Size and overflow

The size props take a length (`0`, or a number with `px`, `%`, `rem`, `em`, `ch`, `dvw` or `dvh`) or an intrinsic keyword (`fit-content`, `min-content`, `max-content`). `inlineSize` and `blockSize` also take `auto`, and the `max` props take `none`. Use `overflow` with a size to clip or scroll content that does not fit. An invalid value is ignored by the browser.

```html
<dds-box
  padding="s"
  border="s"
  overflow="auto"
  block-size="120px"
>
  <p>Content taller than the box scrolls inside it.</p>
</dds-box>
```

#### Accessibility

A box is a generic container to assistive technology. Where the content has meaning, set `role` and `aria-*` on the box itself. `aria-label` has no effect without a `role`.

```html
<dds-box role="region" aria-label="Campaign summary" padding="m" border="s">
  <p>Quarterly summary for all markets.</p>
</dds-box>
```



## Properties

| Property        | Attribute         | Description                                                                                                               | Type                                                                                                                                                                                                         | Default     |
| --------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
| `background`    | `background`      | The surface colour, as a step on the surface scale.                                                                       | `"1" \| "2" \| "3" \| "4" \| "5" \| "6" \| "7" \| "none"`                                                                                                                                                    | `"none"`    |
| `blockSize`     | `block-size`      | The size on the block axis. Takes a length, `auto`, or an intrinsic keyword.                                              | `` "0" \| "auto" \| "fit-content" \| "max-content" \| "min-content" \| `${number}%` \| `${number}ch` \| `${number}dvh` \| `${number}dvw` \| `${number}em` \| `${number}px` \| `${number}rem` \| undefined `` | `undefined` |
| `border`        | `border`          | The border width. The border is always solid.                                                                             | `"m" \| "none" \| "s"`                                                                                                                                                                                       | `"none"`    |
| `borderColor`   | `border-color`    | The border colour, as a step on the border scale. Has no effect unless `border` is set.                                   | `"1" \| "2" \| "3" \| "4" \| "5" \| "6" \| undefined`                                                                                                                                                        | `undefined` |
| `display`       | `display`         | Whether the surface is shown. `auto` leaves the host's own display alone; `none` hides it.                                | `"auto" \| "none"`                                                                                                                                                                                           | `"auto"`    |
| `inlineSize`    | `inline-size`     | The size on the inline axis. Takes a length, `auto`, or an intrinsic keyword.                                             | `` "0" \| "auto" \| "fit-content" \| "max-content" \| "min-content" \| `${number}%` \| `${number}ch` \| `${number}dvh` \| `${number}dvw` \| `${number}em` \| `${number}px` \| `${number}rem` \| undefined `` | `undefined` |
| `maxBlockSize`  | `max-block-size`  | The maximum size on the block axis. Takes a length, `none`, or an intrinsic keyword.                                      | `` "0" \| "fit-content" \| "max-content" \| "min-content" \| "none" \| `${number}%` \| `${number}ch` \| `${number}dvh` \| `${number}dvw` \| `${number}em` \| `${number}px` \| `${number}rem` \| undefined `` | `undefined` |
| `maxInlineSize` | `max-inline-size` | The maximum size on the inline axis. Takes a length, `none`, or an intrinsic keyword.                                     | `` "0" \| "fit-content" \| "max-content" \| "min-content" \| "none" \| `${number}%` \| `${number}ch` \| `${number}dvh` \| `${number}dvw` \| `${number}em` \| `${number}px` \| `${number}rem` \| undefined `` | `undefined` |
| `minBlockSize`  | `min-block-size`  | The minimum size on the block axis. Takes a length or an intrinsic keyword.                                               | `` "0" \| "fit-content" \| "max-content" \| "min-content" \| `${number}%` \| `${number}ch` \| `${number}dvh` \| `${number}dvw` \| `${number}em` \| `${number}px` \| `${number}rem` \| undefined ``           | `undefined` |
| `minInlineSize` | `min-inline-size` | The minimum size on the inline axis. Takes a length or an intrinsic keyword.                                              | `` "0" \| "fit-content" \| "max-content" \| "min-content" \| `${number}%` \| `${number}ch` \| `${number}dvh` \| `${number}dvw` \| `${number}em` \| `${number}px` \| `${number}rem` \| undefined ``           | `undefined` |
| `overflow`      | `overflow`        | How content that overflows the surface is handled.                                                                        | `"auto" \| "clip" \| "hidden" \| "scroll" \| "visible" \| undefined`                                                                                                                                         | `undefined` |
| `padding`       | `padding`         | The space between the surface edge and its content on both axes. `paddingBlock` and `paddingInline` override it per axis. | `"l" \| "m" \| "none" \| "s" \| "xl" \| "xs" \| "xxs"`                                                                                                                                                       | `"none"`    |
| `paddingBlock`  | `padding-block`   | The space on the block axis. Overrides the block value of `padding`.                                                      | `"l" \| "m" \| "none" \| "s" \| "xl" \| "xs" \| "xxs" \| undefined`                                                                                                                                          | `undefined` |
| `paddingInline` | `padding-inline`  | The space on the inline axis. Overrides the inline value of `padding`.                                                    | `"l" \| "m" \| "none" \| "s" \| "xl" \| "xs" \| "xxs" \| undefined`                                                                                                                                          | `undefined` |
| `radius`        | `radius`          | The corner radius.                                                                                                        | `"container" \| "element" \| "full" \| "inner" \| "none" \| "page"`                                                                                                                                          | `"none"`    |


## Slots

| Slot | Description                        |
| ---- | ---------------------------------- |
|      | The content placed on the surface. |


## Dependencies

### Used by

 - [dds-card](../card)

### Graph
```mermaid
graph TD;
  dds-card --> dds-box
  style dds-box fill:#f9f,stroke:#333,stroke-width:4px
```

----------------------------------------------

*Built with [StencilJS](https://stenciljs.com/)*