# Grid

Cells laid out on a grid with visible guide lines between them.

Source: [grid.tsx](https://github.com/jakejarvis/jarvis-ui/blob/main/src/components/ui/grid.tsx)

```tsx
import {
  GaugeIcon,
  GitBranchIcon,
  GlobeIcon,
  LockIcon,
  RefreshCwIcon,
  TerminalIcon,
} from "lucide-react";

import { Grid, GridCell } from "@/components/ui/grid";

const features = [
  {
    icon: GlobeIcon,
    title: "Global edge",
    description: "Pages load from the region nearest each visitor.",
  },
  {
    icon: GitBranchIcon,
    title: "Preview branches",
    description: "Every pull request gets its own address.",
  },
  {
    icon: GaugeIcon,
    title: "Speed insights",
    description: "See how real visitors experience each page.",
  },
  {
    icon: LockIcon,
    title: "Automatic HTTPS",
    description: "Certificates are issued and renewed for you.",
  },
  {
    icon: RefreshCwIcon,
    title: "Instant rollbacks",
    description: "Put any earlier deploy back in one click.",
  },
  {
    icon: TerminalIcon,
    title: "Command line",
    description: "Deploy, inspect and tail logs from a terminal.",
  },
];

export default function GridFeatures() {
  return (
    <Grid columns={{ base: 1, sm: 2, xl: 3 }} rows={{ base: 6, sm: 3, xl: 2 }}>
      {features.map(({ icon: Icon, title, description }) => (
        <GridCell key={title} className="flex flex-col gap-1.5 p-5">
          <Icon className="mb-1.5 size-4 text-icon-muted" />
          <h3 className="text-sm font-medium">{title}</h3>
          <p className="text-sm text-muted-foreground">{description}</p>
        </GridCell>
      ))}
    </Grid>
  );
}
```

## Installation

Add the registry, once per project:

```bash
npx shadcn@latest registry add @jarvis=https://ui.jarv.is/r/{name}.json
```

Then add the component:

```bash
npx shadcn@latest add @jarvis/grid
```

## Usage

```tsx
import { Grid, GridCell } from "@/components/ui/grid";

export function Features() {
  return (
    <Grid columns={{ base: 1, md: 3 }} rows={{ base: 3, md: 1 }}>
      <GridCell className="p-5">Deploys from every branch</GridCell>
      <GridCell className="p-5">Logs you can search</GridCell>
      <GridCell className="p-5">Rollbacks in one click</GridCell>
    </Grid>
  );
}
```

Grid renders its guides, the lines between cells, from its `columns` and `rows`, so set both. Each
`GridCell` fills the next free cell in order, unless its `column` and `row` place it.

Use Grid where the lines are part of the design, as in a feature list or the sections of a landing
page. For cards or a list in a few responsive columns, use Tailwind's `grid` and `grid-cols-*`
utilities directly. Grid is only worth using when its guides show.

### Breakpoints

`columns`, `rows` and a cell's `column`, `row` and `solid` each take an object of values by
breakpoint, such as `{ base: 1, md: 3 }`. A breakpoint takes the value of the one before it unless
it has its own. The breakpoints are Tailwind's container sizes, measured on the grid itself rather
than the viewport, so a Grid lays out the same in a narrow sidebar on a wide screen as on a phone.

| Breakpoint | Grid width  |
| ---------- | ----------- |
| `base`     | Any         |
| `sm`       | 24rem/384px |
| `md`       | 28rem/448px |
| `lg`       | 32rem/512px |
| `xl`       | 36rem/576px |
| `2xl`      | 42rem/672px |
| `3xl`      | 48rem/768px |
| `4xl`      | 56rem/896px |

## Composition

- `Grid`
  - `GridCell`

## Examples

### Basic

Cells without a `column` or `row` fill the grid in order.

```tsx
import { Grid, GridCell } from "@/components/ui/grid";

export default function GridBasic() {
  return (
    <Grid columns={3} rows={2}>
      {[1, 2, 3, 4, 5, 6].map((number) => (
        <GridCell
          key={number}
          className="flex h-20 items-center justify-center font-mono text-sm text-muted-foreground"
        >
          {number}
        </GridCell>
      ))}
    </Grid>
  );
}
```

### Solid cells

`solid` gives a cell the background behind the grid. The guides inside the cell disappear, and the
lines along its edges stay. Without it, the guides show through a cell that spans several columns,
as they do through 5 + 6.

```tsx
import { Grid, GridCell } from "@/components/ui/grid";

const cell = "flex h-20 items-center justify-center font-mono text-sm text-muted-foreground";

export default function GridSolidCells() {
  return (
    <Grid columns={3} rows={2}>
      <GridCell column="span 2" solid className={cell}>
        1 + 2
      </GridCell>
      <GridCell className={cell}>3</GridCell>
      <GridCell className={cell}>4</GridCell>
      <GridCell column="span 2" className={cell}>
        5 + 6
      </GridCell>
    </Grid>
  );
}
```

### Responsive

Resize the page to see the grid go from one column to two to three.

```tsx
import { Grid, GridCell } from "@/components/ui/grid";

export default function GridResponsive() {
  return (
    <Grid columns={{ base: 1, sm: 2, xl: 3 }} rows={{ base: 6, sm: 3, xl: 2 }}>
      {[1, 2, 3, 4, 5, 6].map((number) => (
        <GridCell
          key={number}
          className="flex h-16 items-center justify-center font-mono text-sm text-muted-foreground"
        >
          {number}
        </GridCell>
      ))}
    </Grid>
  );
}
```

### Responsive solid cells

A cell can span, move and become solid at different breakpoints. In this example, 1 + 2 is solid
only from `sm`, where it spans both columns.

```tsx
import { Grid, GridCell } from "@/components/ui/grid";

const cell = "flex h-16 items-center justify-center font-mono text-sm text-muted-foreground";

export default function GridResponsiveSolid() {
  return (
    <Grid columns={{ base: 1, sm: 2, xl: 3 }} rows={{ base: 4, sm: 3, xl: 2 }}>
      <GridCell column={{ sm: "span 2" }} solid={{ sm: true }} className={cell}>
        1 + 2
      </GridCell>
      <GridCell className={cell}>3</GridCell>
      <GridCell className={cell}>4</GridCell>
      <GridCell
        column={{ sm: "span 2", xl: "span 1" }}
        row={{ xl: "1 / 3" }}
        solid
        className={cell}
      >
        5 + 6
      </GridCell>
    </Grid>
  );
}
```

### Row guides only

`guides="rows"` renders only the lines between rows, for a list of rows. `guides="columns"` renders
only the lines between columns. Hide one set only when the layout reads along one axis and the
lines across it would add nothing. If you'd hide both sets, use Tailwind's `grid` utilities
instead.

```tsx
import { Grid, GridCell } from "@/components/ui/grid";

const releases = [
  { version: "v4.2.0", date: "Nov 3", notes: "Faster cold starts in every region." },
  { version: "v4.1.0", date: "Oct 14", notes: "Preview branches get their own logs." },
  { version: "v4.0.0", date: "Sep 22", notes: "A new dashboard and command line." },
];

export default function GridRowGuides() {
  return (
    <Grid columns={4} rows={3} guides="rows">
      {releases.map(({ version, date, notes }) => [
        <GridCell key={`${version}-version`} className="px-4 py-3 font-mono text-sm">
          {version}
        </GridCell>,
        <GridCell
          key={`${version}-date`}
          className="px-4 py-3 text-sm whitespace-nowrap text-muted-foreground"
        >
          {date}
        </GridCell>,
        <GridCell key={`${version}-notes`} column="span 2" className="px-4 py-3 text-sm">
          {notes}
        </GridCell>,
      ])}
    </Grid>
  );
}
```

### Column guides only

```tsx
import { Grid, GridCell } from "@/components/ui/grid";

const stats = [
  { label: "Requests", value: "1.2M" },
  { label: "Cache hit rate", value: "94%" },
  { label: "Median response", value: "38 ms" },
];

export default function GridColumnGuides() {
  return (
    <Grid columns={3} rows={1} guides="columns">
      {stats.map(({ label, value }) => (
        <GridCell key={label} className="flex flex-col gap-1 p-4">
          <span className="text-sm text-muted-foreground">{label}</span>
          <span className="text-xl font-medium tabular-nums">{value}</span>
        </GridCell>
      ))}
    </Grid>
  );
}
```

### Placement

`column` and `row` place a cell, as a number or as a `grid-column` or `grid-row` value such as
`"2 / 4"` or `"span 2"`. Cells without them fill in around the placed ones. Placed cells can
overlap: later cells sit on top, and a solid cell hides what's beneath it.

```tsx
import { Grid, GridCell } from "@/components/ui/grid";

const cell = "flex h-20 items-center justify-center font-mono text-sm text-muted-foreground";

export default function GridPlacement() {
  return (
    <Grid columns={4} rows={2}>
      <GridCell column={1} row={1} className={cell}>
        1
      </GridCell>
      <GridCell column={4} row={1} className={cell}>
        2
      </GridCell>
      <GridCell column="2 / 4" row="1 / 3" solid className="flex items-center p-5 text-sm">
        Spans columns 2 and 3 and both rows.
      </GridCell>
      <GridCell column={1} row={2} className={cell}>
        3
      </GridCell>
      <GridCell column={4} row={2} className={cell}>
        4
      </GridCell>
    </Grid>
  );
}
```

### Square cells

`square` sizes the rows to match the columns, so every cell is square, even with nothing in it.

```tsx
import { Grid } from "@/components/ui/grid";

export default function GridSquare() {
  return <Grid columns={5} rows={2} square className="max-w-md" />;
}
```

### Stacked

Grids placed one after another share the border between them, so sections of a page can each have
their own columns.

```tsx
import { Grid, GridCell } from "@/components/ui/grid";

export default function GridStacked() {
  return (
    <div className="w-full">
      <Grid columns={1} rows={1}>
        <GridCell className="flex flex-col gap-1 p-6">
          <h3 className="text-base font-medium">Ship from your branch</h3>
          <p className="text-sm text-muted-foreground">
            Every push builds and gets its own address.
          </p>
        </GridCell>
      </Grid>
      <Grid columns={{ base: 1, sm: 3 }} rows={{ base: 3, sm: 1 }}>
        {["Build", "Preview", "Promote"].map((step, index) => (
          <GridCell key={step} className="flex items-center gap-2 p-4 text-sm">
            <span className="font-mono text-muted-foreground">0{index + 1}</span>
            {step}
          </GridCell>
        ))}
      </Grid>
    </div>
  );
}
```

## Props

| Part | Extends |
| --- | --- |
| `Grid` | `<div>` |
| `GridCell` | `<div>` |

Base UI's [styling](https://base-ui.com/react/handbook/styling) and [composition](https://base-ui.com/react/handbook/composition) guides say more about `className`, `style` and `render`.

### Grid

| Prop         | Type                                                     | Default | Description                                                                                                                                                                               |
| ------------ | -------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `columns?`   | `GridResponsiveValue<number>`                            | `1`     | How many equal columns the grid has, as a number or an object of counts by breakpoint, such as `{ base: 1, md: 3 }`. Breakpoints apply to the grid's own width.                           |
| `rows?`      | `GridResponsiveValue<number>`                            | `1`     | How many rows the grid has, as a number or an object of counts by breakpoint. The guides are rendered for this many rows.                                                                 |
| `guides?`    | `"all" \| "columns" \| "none" \| "rows"`                 | `"all"` | Which lines to show between the cells: `rows` shows only the horizontal lines, and `columns` only the vertical ones. The outer border always shows.                                       |
| `square?`    | `boolean`                                                | `false` | Sizes the rows so every cell is square.                                                                                                                                                   |
| `className?` | `string`                                                 | —       | CSS class applied to the element.                                                                                                                                                         |
| `style?`     | `React.CSSProperties`                                    | —       | Style applied to the element.                                                                                                                                                             |
| `render?`    | `ComponentRenderFn<HTMLProps, {}> \| React.ReactElement` | —       | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |

### GridCell

| Prop         | Type                                                     | Default | Description                                                                                                                                                                                  |
| ------------ | -------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `column?`    | `GridResponsiveValue<string \| number>`                  | —       | Where the cell sits across the columns, as a `grid-column` value such as `2`, `"span 2"` or `"1 / 3"`, or an object of them by breakpoint. Without it, cells flow into the next free column. |
| `row?`       | `GridResponsiveValue<string \| number>`                  | —       | Where the cell sits down the rows, as a `grid-row` value such as `2`, `"span 2"` or `"1 / 3"`, or an object of them by breakpoint.                                                           |
| `solid?`     | `GridResponsiveValue<boolean>`                           | `false` | Gives the cell the background behind the grid. The guides it covers are hidden, but the lines along its edges stay. Pass an object to make the cell solid only at some breakpoints.          |
| `className?` | `string`                                                 | —       | CSS class applied to the element.                                                                                                                                                            |
| `style?`     | `React.CSSProperties`                                    | —       | Style applied to the element.                                                                                                                                                                |
| `render?`    | `ComponentRenderFn<HTMLProps, {}> \| React.ReactElement` | —       | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.    |
