Layout

How the grid system works.

The layout object

The layout is the grid state. It is an array of items with position and size.

import { type Layout } from "@dnd-grid/react";

const layout: Layout = [
  { id: "a", x: 0, y: 0, w: 4, h: 2 },
  { id: "b", x: 4, y: 0, w: 4, h: 2 },
];

Properties

Prop	Type	Description
`id`	`string`	Required. Unique id, must match the child's `key`.
`x`	`number`	Required. Column index (0-based).
`y`	`number`	Required. Row index (0-based).
`w`	`number`	Required. Width in columns.
`h`	`number`	Required. Height in rows.
`minW`	`number`	Minimum width.
`maxW`	`number`	Maximum width.
`minH`	`number`	Minimum height.
`maxH`	`number`	Maximum height.
`static`	`boolean`	If `true`, the item is locked.
`draggable`	`boolean`	Override grid drag setting.
`resizable`	`boolean`	Override grid resize setting.

For the full LayoutItem shape (constraints, resize handles, data, and more), see the Layout item API reference.

Grid system

The grid uses a column and row coordinate system.

Columns (x): Count is set by cols (default 12).
Rows (y): Rows grow downward; height is set by rowHeight.
Width (w): Number of columns an item spans.
Height (h): Number of rows an item spans.

Compaction

Compaction controls how items pack when space opens up.

import {
  verticalCompactor,
  horizontalCompactor,
  noCompactor,
} from "@dnd-grid/react";

<DndGrid compactor={verticalCompactor} />
<DndGrid compactor={horizontalCompactor} />
<DndGrid compactor={noCompactor} />

Collisions

Choose collision behaviour when items overlap.

Push (default): The dragged item pushes others out of the way.
Prevent collision: The dragged item is blocked by others.
Allow overlap: Items can be placed on top of each other.

import { verticalCompactor, verticalOverlapCompactor } from "@dnd-grid/react";

<DndGrid compactor={{ ...verticalCompactor, preventCollision: true }} />
<DndGrid compactor={verticalOverlapCompactor} />

Persistence

The layout is JSON-serialisable, so saving it is straightforward.

const onLayoutChange = (newLayout) => {
  localStorage.setItem("grid", JSON.stringify(newLayout));
};