# dds-grid



<!-- Auto Generated Below -->


## Overview

A layout container that arranges its children in rows and columns, with a uniform gap and configurable alignment. Place `dds-grid-item` in it to span several columns or rows. It is a generic container to assistive technology; set `role` and `aria-*` on the host where the content has meaning.

## Usage

### Grid

#### Columns and rows

A grid places its children in the tracks you define. Set `gridTemplateColumns` to a CSS track list, such as `repeat(3, 1fr)` for three equal columns or `1fr 2fr` for a narrow column beside a wide one. Without it the grid is a single column. `gridTemplateRows` sizes the rows the same way, and rows you do not size are sized by their content.

```html
<dds-grid grid-template-columns="repeat(3, 1fr)" gap="m">
  <div>One</div>
  <div>Two</div>
  <div>Three</div>
</dds-grid>
```

Both props take a free-form string, so an invalid value is ignored by the browser.

#### Spacing

`gap` spaces rows and columns on the same step of the scale. `rowGap` and `columnGap` override it for one axis each.

```html
<dds-grid grid-template-columns="repeat(2, 1fr)" gap="s" column-gap="xl">
  <div>One</div>
  <div>Two</div>
  <div>Three</div>
  <div>Four</div>
</dds-grid>
```

#### Spanning columns and rows

Any child fills one cell. Wrap a child in `dds-grid-item` and set `colspan` or `rowspan` to make it cover more. A twelve-column grid gives the usual half and third layouts.

```html
<dds-grid grid-template-columns="repeat(12, 1fr)" gap="m">
  <dds-grid-item colspan="12">Header</dds-grid-item>
  <dds-grid-item colspan="8">Main</dds-grid-item>
  <dds-grid-item colspan="4">Aside</dds-grid-item>
</dds-grid>
```

#### Alignment

`alignItems` and `justifyItems` place each item inside its own cell, on the block and inline axes. `alignContent` and `justifyContent` distribute the tracks themselves, and only show when the grid is larger than its tracks.

```html
<dds-grid
  grid-template-columns="repeat(2, 10rem)"
  justify-content="space-between"
  align-items="center"
>
  <div>One</div>
  <div>Two</div>
</dds-grid>
```

#### A surface for the grid

A grid has no surface, padding or border of its own. Put a `dds-box` around it, or inside each cell, to give it one.

```html
<dds-box padding="l" background="2" radius="container">
  <dds-grid grid-template-columns="repeat(3, 1fr)" gap="m">
    <dds-box padding="m" background="4">One</dds-box>
    <dds-box padding="m" background="4">Two</dds-box>
    <dds-box padding="m" background="4">Three</dds-box>
  </dds-grid>
</dds-box>
```

#### Grid or stack

Use a grid where items line up in both directions. For a single row or column, use `dds-stack`. The two nest: a stack of grids stacks full-width rows that each have their own columns.

```html
<dds-stack gap="l">
  <dds-grid grid-template-columns="repeat(2, 1fr)" gap="m">
    <div>One</div>
    <div>Two</div>
  </dds-grid>
  <dds-grid grid-template-columns="repeat(3, 1fr)" gap="m">
    <div>One</div>
    <div>Two</div>
    <div>Three</div>
  </dds-grid>
</dds-stack>
```

#### Accessibility

A grid is a generic container, and visual placement never changes reading or focus order, which follow the order of the children in the document. Put children in the order they should be read, not the order they should appear. Set `role` and `aria-*` on the host where the content has meaning, for example `role="list"` on the grid and `role="listitem"` on each child.



## Properties

| Property              | Attribute               | Description                                                                                                                                                                                         | Type                                                                                                                         | Default     |
| --------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `alignContent`        | `align-content`         | How the rows are distributed on the block axis when the grid is larger than its tracks.                                                                                                             | `"baseline" \| "center" \| "end" \| "normal" \| "space-around" \| "space-between" \| "space-evenly" \| "start" \| "stretch"` | `"normal"`  |
| `alignItems`          | `align-items`           | How items align within their cell on the block axis.                                                                                                                                                | `"baseline" \| "center" \| "end" \| "normal" \| "start" \| "stretch"`                                                        | `"normal"`  |
| `columnGap`           | `column-gap`            | The space between columns, on the inline axis. Overrides the column value of `gap`.                                                                                                                 | `"l" \| "m" \| "none" \| "s" \| "xl" \| "xs" \| "xxs" \| undefined`                                                          | `undefined` |
| `gap`                 | `gap`                   | The space between rows and columns on both axes. `rowGap` and `columnGap` override it per axis.                                                                                                     | `"l" \| "m" \| "none" \| "s" \| "xl" \| "xs" \| "xxs"`                                                                       | `"none"`    |
| `gridTemplateColumns` | `grid-template-columns` | The column tracks, as a CSS track list such as `repeat(3, 1fr)` or `1fr auto`. No scale backs it and the track grammar is too open for an allowlist, so an invalid value is dropped by the browser. | `string \| undefined`                                                                                                        | `undefined` |
| `gridTemplateRows`    | `grid-template-rows`    | The row tracks, as a CSS track list such as `auto 1fr`. No scale backs it and the track grammar is too open for an allowlist, so an invalid value is dropped by the browser.                        | `string \| undefined`                                                                                                        | `undefined` |
| `justifyContent`      | `justify-content`       | How the columns are distributed on the inline axis when the grid is larger than its tracks.                                                                                                         | `"baseline" \| "center" \| "end" \| "normal" \| "space-around" \| "space-between" \| "space-evenly" \| "start" \| "stretch"` | `"normal"`  |
| `justifyItems`        | `justify-items`         | How items align within their cell on the inline axis.                                                                                                                                               | `"baseline" \| "center" \| "end" \| "normal" \| "start" \| "stretch"`                                                        | `"normal"`  |
| `rowGap`              | `row-gap`               | The space between rows, on the block axis. Overrides the row value of `gap`.                                                                                                                        | `"l" \| "m" \| "none" \| "s" \| "xl" \| "xs" \| "xxs" \| undefined`                                                          | `undefined` |


## Slots

| Slot | Description                                                                                                |
| ---- | ---------------------------------------------------------------------------------------------------------- |
|      | The elements arranged in the grid. Accepts any element, and `<dds-grid-item>` where a child needs to span. |


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

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