# Dashboard Grid

A grid of dashboard cards on 12 columns that people rearrange and resize in whole cells, with the pointer or the keyboard; stacks on tablets and phones.

- Category: Navigation & Layout
- Page: https://wunderui.com/components/dashboard-grid
- Tier: Core and Pro

## Install

Dashboard Grid ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { DashboardGrid, DashboardGridBreakpoint, DashboardGridItem, DashboardGridProps, DashboardGridSize } from "@wunderui/react"
```

## Anatomy

- `DashboardGrid`: A CSS grid of 12 columns with 80 px rows and 16 px gaps that hugs its content. It measures its own width: 6 columns below 1024 px, 1 below 640 px.
- `Card frame`: Wraps what renderItem returns. In editing mode a dashed border-control outline marks the card; a grabbed or dragged card gets the primary outline and the lg shadow.
- `Move handle`: A square 24 px icon button in the top-start corner of the card in editing mode. It sits over the card's top-start corner, so keep the top 32 px of a card free while editing: the grid is a `group/grid`, so `group-data-editing/grid:pt-10` on the card makes the room. Drag it, or press Enter to grab, the arrow keys to move, Shift and the arrow keys to resize, Enter to drop and Escape to cancel; an assertive live region says where the card is.
- `Resize corner`: A 24 px corner at the bottom right for the pointer; the keyboard resizes from the handle.
- `Placeholder`: While a card is dragged, a grey dashed cell on bg-page shows where it will land.
- `Actions`

## Best practices

### When to use

- Use a Dashboard Grid when people arrange their own board of cards. For a fixed layout use a plain CSS grid.

### Do

- Give every item a label; announcements use it ("Revenue moved to column 3, row 1").
- Edit on a draft: Edit layout copies the items, Save keeps them, Cancel throws them away.
- Set minW and minH so a card never gets too small for its chart.
- Give ChartCard and MetricCard fill inside a cell so the chart takes the cell height, set columnGap and rowGap apart (cards side by side 24, stacked 16), sizes per breakpoint with layouts, and card buttons with renderActions instead of a header inside the card.

### Don't

- Don't make the cards themselves draggable; the handle is the one place to grab, so clicks inside a card still work.

## API reference

### DashboardGrid

| Prop | Type | Default | Description |
|---|---|---|---|
| items* | DashboardGridItem[] |  |  |
| renderItem* | (id: string) => React.ReactNode |  |  |
| breakpoints | DashboardGridBreakpoint[] | DEFAULT_BREAKPOINTS | Default: tablet below 1024 px → 6 columns, phone below 640 px → 1 column. Editing works at full width only. |
| columnGap | number |  | Space between cards side by side in px; defaults to `gap`. |
| columns | number | 12 | Columns at full width. |
| editing | boolean | false | Shows the frame, the move handle and the resize corner on every card. |
| gap | number | 16 | Space between cards in px (both directions; `columnGap` and `rowGap` override it). |
| layouts | Record<number, DashboardGridSize[]> |  | Sizes per breakpoint, keyed by its column count: `{ 6: [{ id: "revenue", w: 6 }], 1: [{ id: "table", h: 12 }] }`. A card listed there takes that width and height when the grid has that many columns; the others scale their width and keep th… |
| onLayoutChange | (items: DashboardGridItem[]) => void |  | Called with all items after a drop or a resize (pointer or keyboard). |
| renderActions | (id: string) => React.ReactNode |  | Extra controls of a card in editing mode (duplicate, remove …), top end, beside the move handle. |
| rowGap | number |  | Space between stacked cards in px; defaults to `gap`. Dragging snaps by `rowHeight + rowGap`. |
| rowHeight | number | 80 | Height of one row in px. |

Also accepts React.HTMLAttributes attributes.

## Examples

### Width: 6 columns on a tablet, 1 on a phone

## In context

### Editable board: draft, save or cancel

Edit layout turns on the frames and handles and works on a copy; Save layout keeps it and Cancel throws it away. onLayoutChange runs after every drop or resize, never while dragging.

### Cards that fill their cells, sizes per breakpoint and card actions

ChartCard and MetricCard with `fill` take the height of their cell: the chart gets what the header leaves it. `columnGap` and `rowGap` set the two gaps apart (dragging snaps by the row height plus the row gap). `layouts` gives a card another width or height when the grid has 6 or 1 columns, and `renderActions` puts buttons beside the move handle while editing.

## For AI agents

`get_component("dashboard-grid")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
