# Grid

Helps create a layout that conforms to a 12-point grid system.

## Design & usage guidelines

The Grid is divided up into 12 columns. The `Grid.Cell` child sets how many of
the 12 columns it takes as a width via `size`. The `Grid.Cell` also includes
breakpoints of `xs`, `sm`, `md`, `lg`, and `xl`. Those sizes strictly follow our
[Design Breakpoints](/design/breakpoints).

As an example, let's say you have a
[three column grid](/storybook/web/?path=/story/components-layouts-and-structure-grid--three-columns)
that goes side by side with a 50/25/25 split on medium-sized screens and up.
But, on a small-sized screen, it stacks on top of each other.

The way you'd achieve that is to:

* Set the `Grid.Cell` child to have a size for `xs` and `md`
  * example: `{ xs: number, md: number }`
* All `xs` would be set to `12` so it fills the whole width and automatically
  stacks on extra-small and small screens
* The `md` would then get
  * `6` on Column 1
  * `3` on Column 2
  * `3` on Column 3
* If you sum up the values for `md`, you'd get 12.
  * If you set the last column to be 4, it'll sum up to 13 and pushes that last
    column down

## Related components

Use [Flex](../Flex/Flex.md) inside of Grid to create complex layouts without
needing custom wrappers.

Use [Content](../Content/Content.md) to evenly space elements in a simple
one-directional layout.

### Visualizing the grid lines

If you use a Chromium browser like Google Chrome, Arc, or Safari, you can follow
Chrome's
[Inspect CSS grid layouts](https://developer.chrome.com/docs/devtools/css/grid/)
by using the dev tools.


## Developer notes

The `gap` prop currently accepts both boolean values and semantic spacing
tokens. However, using a boolean is deprecated and will be removed in a future
release. The deprecation is communicated through JSDoc comments, which will show
warnings in IDEs and during development. This helps identify and migrate
existing usages, as well as remind developers to use a semantic spacing token
(`small`, `base`, `large`, etc.) when introducing new Grids.

If you find yourself implementing `gap="none"` and the Grid consists only of
Input components, consider using an [InputGroup](../InputGroup/InputGroup.md)
instead.


## Props

### Web

#### Grid

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `children` | `ReactNode` | Yes | — | `Grid.Cell` children |
| `alignItems` | `"center" | "end" | "start" | "stretch"` | No | `start` | Adjust the alignment of columns. We only support a few select properties from `align-items` due to the nature of the ... |
| `gap` | `GapSpacing | boolean` | No | `true` | Add spacing between elements. Can be a boolean for default spacing, or a semantic token for custom spacing. @deprecat... |

#### Grid.Cell

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `size` | `{ xs?: ColumnSizes; sm?: ColumnSizes; md?: ColumnSizes; lg?: ColumnSizes; xl?: ColumnSizes; }` | Yes | — | Set how many columns wide the cell is in the grid |