` attributes(`
id`, `aria-*`, `data-*`, event handlers, `style`, etc.) flow through. The grid’s
own layout styles (`gridTemplateColumns`, `gridAutoRows`) override any user-supplied`
style` for those properties. Tile gap is owned by a design-system token; override
it with `--wp-grid-gap` (see [Theming with CSS variables).
#### [Child-level props](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-grid/?output_format=md#child-level-props)
Children render with the layout entry that matches their `key`. An
optional prop
read off the child lets you keep controls interactive while edit mode is on:
| Child prop | Type | Description |
| `actionableArea` | `ReactNode` | Content rendered above the draggable surface of the grid item. Useful for close buttons, menus, or links that must stay clickable in edit mode. |
### [Modes](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-grid/?output_format=md#modes)
#### [Fixed columns](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-grid/?output_format=md#fixed-columns)
```language-jsx
{ children }
```
#### [Responsive](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-grid/?output_format=md#responsive)
Columns are computed from container width using `minColumnWidth` as
the lower bound
per column. A `ResizeObserver` recomputes on container resize.
```language-jsx
{ children }
```
In responsive mode, layout items can provide an `order` to control
display order
independently of array position.
#### [Edit mode](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-grid/?output_format=md#edit-mode)
When `editMode` is true:
* Items become draggable (powered by `@dnd-kit`). The original tile
stays in place
as a dashed placeholder while a clone follows the cursor through `
`.
* A resize handle appears on the bottom-right of each item. A
solid outline previews
the target size as the cursor moves.
* While any tile is dragging or resizing, `actionableArea` content
on every tile
is set `inert` so hovers on other tiles can’t steal the gesture.
* `onChangeLayout` fires after drop or resize with the new layout.
* `onPreviewLayout` fires continuously during the interaction for
live feedback;
the committed layout is still emitted via `onChangeLayout`.
* Sibling tiles animate into their new positions when the layout
reflows.
---
## [DashboardLanes](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-grid/?output_format=md#dashboardlanes)
A masonry-style surface aligned with `display: grid-lanes`. Items
declare a column
span; heights are driven by content; placement follows a source-ordered, shortest-
lane skyline with a `flow-tolerance` tiebreaker.
The layout model and the placement algorithm are described in
[Introducing CSS Grid Lanes](https://webkit.org/blog/17660/introducing-css-grid-lanes/)
on the WebKit blog. This package implements the same model in JavaScript so it works
today on browsers that do not yet support `display: grid-lanes` natively; the skyline
+ tolerance core is adapted from Simon Willison’s [CSS Grid Lanes Polyfill](https://tools.simonwillison.net/grid-lanes-polyfill.js)(
MIT). Once native support lands across browsers, the polyfill can be removed without
any public API change.
### [Usage](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-grid/?output_format=md#usage-2)
```language-jsx
import { DashboardLanes } from '@wordpress/grid';
const layout = [
{ key: 'a' },
{ key: 'hero', width: 2 },
{ key: 'b' },
{ key: 'c' },
];
function Pinboard() {
const [ current, setCurrent ] = useState( layout );
return (
A
Hero (spans 2 lanes)
B
C
);
}
```
Each child **must** have a `key` prop that matches an entry in the
`layout` array.
Children without a matching layout entry render at the end of the surface without
explicit placement and fall through the lanes auto-flow.
### [Layout model](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-grid/?output_format=md#layout-model-2)
```typescript
interface DashboardLanesLayoutItem {
key: string; // matches child key
width?: number; // lanes to span (default 1)
lane?: number; // 0-indexed: pin to a specific lane
order?: number; // lower values render first
}
```
There is no `height` field: lanes pack tiles vertically using each
tile’s intrinsic
content height.
There is no `'fill'`: with auto-placement, no item is “left over”
in a row; the
algorithm always finds a lane.
`'full'` (span the entire surface width) is expressed by setting
`width` to the
lane count.
To anchor a tile to a specific column, set `lane` to its 0-indexed
position. Pinned
tiles are placed before auto-placed ones, so auto items flow around them; out-of-
range values (negative, or beyond `columns - width`) are clamped.
### [Props](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-grid/?output_format=md#props-2)
| Prop | Type | Default | Description |
| `layout` | `DashboardLanesLayoutItem[]` | — | Required. Span and order keyed by child `key`. |
| `children` | `ReactNode` | — | Required. Each child needs a `key` matching a layout entry. |
| `columns` | `number` | `6` | Total lanes (fixed mode). |
| `minColumnWidth` | `number` | — | If set, enables responsive mode: lane count derived from container width. Mutually exclusive with `columns`. |
| `flowTolerance` | `number` | `16` | Pixel tolerance for source-order tiebreaking when two candidate lanes have similar baselines. Larger values keep tiles closer to reading order at the cost of bigger empty regions. |
| `rowUnit` | `number` | `4` | Snap unit for the polyfill’s `grid-row-start` math. Smaller values produce sharper placement at the cost of a larger implicit row count. Ignored on browsers with native `display: grid-lanes` support. |
| `editMode` | `boolean` | `false` | Enables drag-to-reorder and horizontal resize. |
| `onChangeLayout` | `( layout ) => void` | — | Fired when the user commits a drag or resize. |
| `onPreviewLayout` | `( layout ) => void` | — | Fired continuously during a drag or resize. |
| `renderResizeHandle` | `ComponentType< ResizeHandleRenderProps >` | — | Override the default side-grip resize handle. See [Custom resize handle](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-grid/?output_format=md#custom-resize-handle). |
| `renderDragPreview` | `ComponentType< DragPreviewRenderProps >` | — | Wrap the dragged-clone visual mounted inside ``. See [Custom drag preview](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-grid/?output_format=md#custom-drag-preview). |
| `renderGridOverlay` | `ComponentType< GridOverlayRenderProps >` | — | Override the default edit-mode overlay that visualizes the lane tracks. Receives the resolved `columns` and `isActive`; lanes pass no row metrics because heights are content-driven. |
| `className` | `string` | — | Extra class on the surface root. |
| `style` | `CSSProperties` | — | Inline styles on the surface root; the surface’s own layout styles win over them. |
### [Native vs polyfill](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-grid/?output_format=md#native-vs-polyfill)
`DashboardLanes` checks `CSS.supports( 'display', 'grid-lanes' )`
once at mount.
* When supported (Safari 26+, others as the spec ships), the
component emits `
display: grid-lanes` and the spec’s CSS, and lets the engine handle layout. The
placement layer mounts no per-tile observers; the only `ResizeObserver` left
is the container-width one used for responsive mode and resize-step math.
* When unsupported, an internal hook (`useLanePlacement`) measures
each tile’s
height with a `ResizeObserver`, runs the source-ordered shortest-lane algorithm,
and emits explicit `grid-column-start` and `grid-row-start` / `grid-row-end:
span N` values on each tile.
The same DOM contract is preserved in both paths; the visual is the
same.
### [Edit mode](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-grid/?output_format=md#edit-mode-2)
Drag-to-reorder works the same as in `DashboardGrid`. Resize is
**horizontal-only**:
tile heights are content-driven, so there is no vertical resize gesture. The default
handle is a vertical bar centered on the trailing edge; the cursor is `ew-resize`.
Sibling tiles animate into their new positions when the layout
reflows.
---
## [Shared topics](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-grid/?output_format=md#shared-topics)
### [Performance](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-grid/?output_format=md#performance)
`onPreviewLayout` re-renders the parent on every gesture frame. To
keep the components’
internal children walk from re-running each frame, **memoize the children array**
when its content is stable:
```language-jsx
const tiles = useMemo(
() => layout.map( ( item ) => ... ),
[ layout ]
);
return (
{ tiles }
);
```
Without it the surface still works but walks the children on every
preview update;
the overhead is minor up to ~50 tiles and grows from there. For `DashboardLanes`,
placement runs in a `useLayoutEffect` throttled to one frame per measurement burst.
### [Accessibility](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-grid/?output_format=md#accessibility)
Drag-to-reorder is operable from the keyboard via `@dnd-kit`‘s
keyboard sensor:
* `Tab` to focus a tile.
* `Space` to pick it up.
* Arrow keys to move it between positions.
* `Space` to drop, or `Escape` to cancel.
Resize handles are currently pointer-only.
### [Custom resize handle](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-grid/?output_format=md#custom-resize-handle)
Both components accept a `renderResizeHandle` prop to override the
default visual.
The surface owns the resize math (column/row stepping, throttled delta loop, layout
commit) and passes the gesture wiring (`ref`, `listeners`, `attributes`) as props
for the consumer to spread on the element that should receive pointer events. The
dnd-kit `` for the resize gesture is internal to the handle wrapper;
consumers do not need to mount their own.
```language-jsx
import { Icon } from '@wordpress/ui';
import { resizeCornerNE } from '@wordpress/icons';
function CustomResizeHandle( {
ref,
listeners,
attributes,
verticalResizable,
} ) {
return (
);
}
{ tiles }
;
```
The component receives:
| Prop | Type | Description |
| `ref` | `( node ) => void` | dnd-kit ref; assign on the gesture-bearing element. |
| `listeners` | `SyntheticListenerMap \| undefined` | Pointer/keyboard listeners; spread on the same element. |
| `attributes` | `DraggableAttributes` | Accessibility/dnd-kit attributes; spread alongside `listeners`. |
| `verticalResizable` | `boolean` | False on `DashboardLanes` and on `DashboardGrid` with `rowHeight: 'auto'`. Useful for adapting cursor or visual cue. |
| `isResizing` | `boolean` | True while the user is actively dragging this handle. Use it to swap colors, icons, or transforms during the gesture. |
| `itemId` | `string` | Owning tile’s `key`. |
The handle is only mounted while the surface is in edit mode
(`editMode={ true }`),
so the custom component never has to short-circuit on a disabled state.
### [Custom drag preview](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-grid/?output_format=md#custom-drag-preview)
While a tile is being dragged, dnd-kit clones it into a ``
that follows
the cursor. Both surfaces wrap that clone with a thin **functional frame** (`scale`,`
cursor: grabbing`, `pointer-events: none) that advertises the lift, but they do
not impose visual chrome on top: any styles the consumer applied to the tile children
carry through to the dragged clone unchanged.
When the dragged state should look structurally different from the
persistent tile(
a stronger shadow, a different border, an extra badge…), pass a `renderDragPreview`
component. The surface mounts it inside the functional frame and supplies the cloned
children plus the active tile’s `key`:
```language-jsx
import { DashboardGrid } from '@wordpress/grid';
import type { DragPreviewRenderProps } from '@wordpress/grid';
function DragPreview( { children }: DragPreviewRenderProps ) {
return (
{ children }
);
}
{ tiles }
;
```
The component receives:
| Prop | Type | Description |
| `children` | `ReactNode` | The cloned tile content the surface mounts inside ``. Place it where the visual wrapper expects the tile body. |
| `itemId` | `string` | Owning tile’s `key`. Useful when chrome varies by tile. |
For token-only tweaks (lift scale, placeholder opacity, outline
color, placeholder
radius), prefer the [CSS variables](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-grid/?output_format=md#theming-with-css-variables)
below; reach for `renderDragPreview` only when the dragged state needs markup the
persistent tile does not have.
### [Theming with CSS variables](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-grid/?output_format=md#theming-with-css-variables)
Both surfaces expose a small set of CSS custom properties for
visuals that need
to flex between consumers without writing a render prop. Override them on any ancestor
of the surface root (or on the root itself via `style`). All values fall back to
sensible defaults.
| Variable | Default | Applies to |
| `--wp-grid-gap` | `var(--wpds-dimension-gap-xl)` | Gap between tiles on `DashboardGrid`, `DashboardLanes`, and the edit overlay. |
| `--wp-grid-drag-preview-scale` | `1.05` | Lift scale of the drag-preview functional frame. Set to `1` to disable the lift. |
| `--wp-grid-drag-preview-radius` | `0` | Border radius of the drag-preview functional frame so the lift shadow follows the consumer’s tile shape. |
| `--wp-grid-placeholder-opacity` | `0.4` | Opacity of the placeholder tile (the original item while a drag is in flight). |
| `--wp-grid-placeholder-outline-style` | `dashed` | Outline style of the drag placeholder (for example `solid` or `dotted`). |
| `--wp-grid-resize-preview-outline-style` | `solid` | Border style of the resize-preview overlay (for example `dashed` or `dotted`). |
| `--wp-grid-placeholder-outline-color` | `var(--wpds-color-stroke-interactive-brand)` | Outline color of the placeholder and of the resize-preview overlay. |
| `--wp-grid-placeholder-radius` | `0` | Border radius of the placeholder, used to match the consumer’s tile shape so the outline traces the right silhouette. |
| `--wp-grid-overlay-tile-bg` | `var(--wpds-color-background-surface-neutral-weak)` | Background of the marker tiles painted by the default edit-mode overlay. |
---
## [Contributing to this package](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-grid/?output_format=md#contributing-to-this-package)
This is an individual package that’s part of the Gutenberg project.
The project
is organized as a monorepo. It’s made up of multiple self-contained software packages,
each with a specific purpose. The packages in this monorepo are published to [npm](https://www.npmjs.com/)
and used by [WordPress](https://make.wordpress.org/core/) as well as other software
projects.
To find out more about contributing to this package or Gutenberg as a
whole, please
read the project’s main [contributor guide](https://github.com/WordPress/gutenberg/tree/HEAD/CONTRIBUTING.md).
First published
June 16, 2026
Last updated
June 16, 2026
Edit article
[ Improve it on GitHub: @wordpress/grid ](https://github.com/WordPress/gutenberg/edit/trunk/packages/grid/README.md)
[ Previous: @wordpress/global-styles-ui](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-global-styles-ui/)
[ Next: @wordpress/hooks](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-hooks/)