# Grid

Lays out children on a responsive grid.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Grid.tsx)

## Overview

Grid places children on equal tracks, either a fixed `columns` count or as many as the width allows with `fit`.

## Examples

### Basic

```tsx
import { Grid, Inset, style } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <Grid columns="3" gap="16">
      {[1, 2, 3].map((n) => (
        <Inset key={n} space="16" {...styles.card()}>
          Column {n}
        </Inset>
      ))}
    </Grid>
  )
}

namespace styles {
  export const card = style({ backgroundColor: 'background.elevated', borderRadius: 'sm' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Grid/Basic.tsx)

### Fit

Set `fit` to `small`, `medium`, or `large` for tracks of at least 10rem, 14rem, or 20rem. It overrides `columns`.

```tsx
import { Grid, Inset, style } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <Grid fit="medium" gap="16">
      {[1, 2, 3, 4].map((n) => (
        <Inset key={n} block="24" inline="32" {...styles.card()}>
          Fit {n}
        </Inset>
      ))}
    </Grid>
  )
}

namespace styles {
  export const card = style({ backgroundColor: 'background.elevated', borderRadius: 'sm' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Grid/Fit.tsx)

### Columns

Set `columns` to `1`, `2`, `3`, `4`, `6`, or `12` equal tracks.

```tsx
import { Grid, Inset, Stack, style } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <Stack gap="24">
      {(['2', '3', '4'] as const).map((columns) => (
        <Grid columns={columns} gap="8" key={columns}>
          {Array.from({ length: Number(columns) }, (_, index) => (
            <Inset key={index} space="16" {...styles.card()}>
              {columns} columns
            </Inset>
          ))}
        </Grid>
      ))}
    </Stack>
  )
}

namespace styles {
  export const card = style({ backgroundColor: 'background.elevated', borderRadius: 'sm' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Grid/Columns.tsx)

### Gap

Set `gap` to a spacing token. `rowGap` and `columnGap` override it on one axis.

```tsx
import { Grid, Inset, style } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <Grid columnGap="8" columns="3" rowGap="32">
      {[1, 2, 3, 4, 5, 6].map((n) => (
        <Inset key={n} space="16" {...styles.card()}>
          Column {n}
        </Inset>
      ))}
    </Grid>
  )
}

namespace styles {
  export const card = style({ backgroundColor: 'background.elevated', borderRadius: 'sm' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Grid/Gap.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { Grid } from '@tempoxyz/ds'

<Grid />
```

## Guidelines

### When to Use

* Lay out similar items, such as metric tiles, token balance cards, or API key cards.
* Build a two-dimensional page layout with a fixed structure, such as a 12-column dashboard.

### When Not to Use

* Use [Table](/docs/components/table) for records to compare across columns, such as transactions.
* Use [Stack](/docs/components/stack) for one column, and [Inline](/docs/components/inline) for one row.

### Prefer Fit Over Fixed Columns

**Do:** Set `fit` so tiles drop to fewer columns as the width shrinks.

```tsx
/**
 * Do example for "Prefer Fit Over Fixed Columns" on the Grid page.
 * Set `fit` so tiles drop to fewer columns as the width shrinks.
 * @module
 */
import { Grid, style, Surface } from '@tempoxyz/ds'

const metrics = [
  ['TPS', '4,218'],
  ['Block time', '0.5s'],
  ['Finality', '0.6s'],
] as const

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Grid fit="small" gap="12" {...styles.canvas()}>
      {metrics.map(([label, value]) => (
        <Surface key={label} size="medium">
          <span {...styles.label()}>{label}</span>
          <span {...styles.value()}>{value}</span>
        </Surface>
      ))}
    </Grid>
  )
}

namespace styles {
  export const canvas = style({
    backgroundColor: 'background.primary',
    borderRadius: 'sm',
    boxSizing: 'border-box',
    padding: '12',
    width: '100% !custom',
  })

  export const label = style({
    color: 'content.secondary',
    display: 'block',
    typography: 'body.b3',
  })

  export const value = style({ display: 'block', typography: 'heading.h3' })
}
```

**Don't:** Force four fixed columns into a narrow container.

```tsx
/**
 * Don't example for "Prefer Fit Over Fixed Columns" on the Grid page.
 * Don't force four fixed columns into a narrow container.
 * @module
 */
import { Grid, style, Surface } from '@tempoxyz/ds'

const metrics = [
  ['TPS', '4,218'],
  ['Block time', '0.5s'],
  ['Finality', '0.6s'],
  ['Gas price', '0.1 gwei'],
] as const

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Grid columns="4" gap="12" {...styles.canvas()}>
      {metrics.map(([label, value]) => (
        <Surface key={label} size="medium">
          <span {...styles.label()}>{label}</span>
          <span {...styles.value()}>{value}</span>
        </Surface>
      ))}
    </Grid>
  )
}

namespace styles {
  export const canvas = style({
    backgroundColor: 'background.primary',
    borderRadius: 'sm',
    boxSizing: 'border-box',
    padding: '12',
    width: '100% !custom',
  })

  export const label = style({
    color: 'content.secondary',
    display: 'block',
    typography: 'body.b3',
  })

  export const value = style({ display: 'block', typography: 'heading.h3' })
}
```

### Change Columns at Breakpoints

If a layout needs a set count per width, change `gridTemplateColumns` under a [breakpoint](/docs/foundations/layout#breakpoints) key. Write the narrowest layout as the base style.

* **Base (0 to 767px):** One column on phones, with no media key.
* **Tablet ('@media 768'):** More columns from 48rem.
* **Desktop ('@media 1024'):** The full count from 64rem. Use `'@media <1024'` for anything narrower.

### Pick a Gap From the Scale

* **Cards (24):** The default, for cards.
* **Dense Tiles (12 or 16):** For dense dashboard tiles.

## Accessibility

Grid has no role, name, or keyboard behavior.

### Semantics

* **Default Element (div):** Has no role. Screen readers pass over it.
* **Semantic Element (render):** If the children are items or links, render a list or nav, such as `render={<ul />}`.

### Your Responsibilities

* **Match DOM and Visual Order (Tab):** Don't reorder children with CSS or grid placement. Reading and focus follow the DOM ([SC 1.3.2](https://www.w3.org/WAI/WCAG22/Understanding/meaningful-sequence.html), [SC 2.4.3](https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html)).

## Related

[Surface](/docs/components/surface)

Use for the cards inside a grid.

[Table](/docs/components/table)

Use for comparing records.

[Dashboards](/docs/patterns/dashboards)

Covers metric tile layouts.

[Responsive Layout](/docs/patterns/responsive-layout)

Covers adapting pages across breakpoints.
