Grid

When to use

Use Grid to place children in equal-width columns: page regions, card grids, dashboard widgets. The number of columns can change with the viewport width.

When not to use

• For tabular data: Use a table for data with row and column headers. Grid does layout only and carries no table meaning.
• For one-direction flow: Use Stack for vertical and Inline for horizontal.
• For unequal column widths: Grid produces equal columns only; for different widths, span cells with span.
• For a box look: If you need padding, a surface or a border, wrap each cell in a Box.

Anatomy

Grid has two parts:

1. Grid: a display: grid container. columns and gap apply to this element.
2. Cell: Grid.Item (data-part="item"). span sets how many columns it takes. Another element can also be a direct child; it takes one column.

Behaviour

• Grid is static: it does not change on hover, click or focus, and it is not in the tab order.
• Defaults: columns 1, gap lg.
• Breakpoints: base below 1024 px, md from 1024 px (Tailwind lg:), lg from 1440 px. A breakpoint without a value keeps the value of the smaller one.
• Children fill left to right, row by row, in DOM order; there is no prop to reorder them.

Guidelines

Start with one column on narrow screens

Keep base small and add columns with md and lg; on a narrow screen the content stays readable.

First item

Second item

Do`base` 1, `md` 2: columns are added as the screen widens.

First item

Second item

Third item

Don'tThree columns at every width: on a narrow screen the cells get too narrow.

Do not use a grid instead of a data table

Use a table for data with row and column headers; Grid does not pass that relation to a screen reader.

Card title

Card title

DoCards in a Grid; each card is an independent piece of content.

Field labelSample textField labelSample text

Don'tLabels and values in a Grid: the relation is visual only.

Content

• Grid carries no text of its own.
• When you pass render={<ul />}, give every Grid.Item render={<li />}.
• Keep example text neutral: “First item”, “Card title”.

Related components

• Stack: To lay out the inside of a cell vertically.
• Inline: To lay out the inside of a cell horizontally.
• Box: To give a cell padding, a surface and a border.