---
title: Grid
description: Arrange related specimens in responsive columns.
sidebar:
  order: 2
---

import previewCode from "../../snippets/grid.mdx?raw";
import threeColumnsCode from "../../snippets/grid-three-columns.mdx?raw";
import example0 from "../../snippets/grid-compact.mdx?raw";

<ComponentPreview path="grid" code={previewCode} />

## Usage

Wrap prose or other components in `Grid`. Nested built-in components receive
the current page’s brand, interface strings, and direction automatically.

```mdx
<Grid cols={2}>
  <Figure caption="Front" />
  <Figure caption="Back" />
</Grid>
```

These figures render draft placeholders until you provide `src`. For image
imports and captions, see [Figure](/components/figure). The preview’s Code tab
includes an image import relative to a content-root page; use your own asset and
adjust the path for nested or localized content.

## Examples

### Arrange three specimens

Use `cols` to choose the column count from `48rem` upward. This example uses the
standard three-column layout and default spacing, then stacks its draft figures
on smaller screens. The opening preview demonstrates two columns and a larger gap.

<ComponentPreview path="grid-three-columns" code={threeColumnsCode} />

### Keep two columns on small screens

Set `colsSm={2}` to keep specimens side by side on narrow screens. A smaller spacing token brings them closer together.

<ComponentPreview path="grid-compact" code={example0} />

## Responsive behavior

Below `48rem`, the grid uses `colsSm`; at `48rem` and above, it uses `cols`.
The breakpoint follows the available width of the browser viewport, including
inside an embedded preview. Resize the page to compare the layouts.

Children render in document order. Use positive whole numbers for column counts
and spacing tokens such as `var(--space-l)` for gaps.

## API reference

| Prop | Type | Default | Description |
| - | - | - | - |
| `cols?` | `number` | `3` | Columns from the medium breakpoint up. |
| `colsSm?` | `number` | `1` | Columns on small screens. |
| `gap?` | `string` | `var(--space-m)` | Any CSS length, or a --space-* value. |
| `class?` | `string` | - | Additional class on the outer element. |