---
title: Layout Grid
description: Illustrate a composition grid with columns, margins, gutters, and supporting specifications.
sidebar:
  order: 28
---

import previewCode from "../../snippets/layout-grid.mdx?raw";
import example0 from "../../snippets/layout-grid-mobile.mdx?raw";

import defaultCode from "../../snippets/layout-grid-default.mdx?raw";

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

## Usage

Use `LayoutGrid` to document a layout specification. With no props, it draws a
12-column canvas at a `16 / 9` aspect ratio.

```mdx
<LayoutGrid />
```

The default preview adds a label and specification row. This diagram describes
a composition; to arrange actual page content, use [Grid](/components/grid).

## Examples

### Start with the default grid

With no props, the diagram uses its default columns, gutter, margin, and canvas
ratio, without a label or specification rows.

<ComponentPreview path="layout-grid-default" code={defaultCode} />

### Annotate a desktop composition

Supply a label, explicit dimensions, and `specs` to explain the intended layout.

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

### Describe a mobile composition

Use fewer columns and a portrait ratio to document a narrow canvas. Include the
actual dimensions in `specs` so readers can reproduce the grid.

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

## Diagram scale

The drawing scales the stated margin to one quarter and the gutter to one half
so the diagram stays readable. These values affect the drawing; they do not
configure the website's layout. Add `specs` when the real dimensions need to
appear as text below the diagram.

Use positive whole numbers for columns and CSS lengths for margins and gutters.
The component has no content slots.

## API reference

| Prop | Type | Default | Description |
| - | - | - | - |
| `columns?` | `number` | `12` | Column count. |
| `gutter?` | `string` | `"30px"` | CSS length; drawn at half the stated gutter. |
| `margin?` | `string` | `"100px"` | CSS length; drawn at one quarter of the stated margin. |
| `ratio?` | `string` | `"16 / 9"` | width / height of the canvas being described. |
| `label?` | `string` | - | e.g. "Desktop · 1440 px and up". |
| `specs?` | `Array<{ term: string; value: string }>` | `[]` | Rows of specs printed beneath the diagram. |
| `class?` | `string` | - | Additional class on the outer element. |