@wordpress/grid

Grid

A collection of grid layout components for arranging tiles in dashboard-style surfaces.

This package exposes two components, each implementing a different layout model:

• DashboardGrid is a 2D packed grid: tiles declare explicit (width, height) spans in column/row units and can span multiple columns and rows.
• DashboardLanes is a masonry-style surface aligned with the emerging WebKit spec display: grid-lanes. Tiles declare a column span only; heights are driven by content; placement follows a source-ordered, shortest-lane skyline with a flow-tolerance tiebreaker.

Installation

Install the module:

npm install @wordpress/grid --save

This package assumes that your code will run in an ES2015+ environment. If you're using an environment that has limited or no support for such language features and APIs, you should include the polyfill shipped in @wordpress/babel-preset-default in your code.

Setup

Component styles are CSS Modules injected at runtime when a component mounts; there is no stylesheet to enqueue or import.

Visual defaults (tile gap, elevation, motion, placeholder strokes) read the design tokens that @wordpress/theme publishes as --wpds-* CSS custom properties.

Within standard WordPress editor screens

In standard WordPress editor screens (such as the post editor or the site editor), the design tokens stylesheet is managed centrally by Gutenberg. You don't need to add any setup yourself.

Elsewhere

Install and load the design tokens stylesheet in your application:

npm install @wordpress/theme

import '@wordpress/theme/design-tokens.css';

Without the tokens the components stay functional, but gaps, elevations, and interaction visuals lose their intended values. Alternatively, define the --wpds-* custom properties the package consumes yourself.

Choosing a component

Both components here are higher-level: the user (not the developer) places and resizes tiles, and the result is emitted through onChangeLayout. For a static CSS Grid with no spans, drag, or per-item state, use __experimentalGrid from @wordpress/components.

DashboardGrid

A 2D packed grid where each child has an explicit column and row span.

Usage

import { DashboardGrid } from '@wordpress/grid';

const layout = [
	{ key: 'a', width: 2, height: 2 },
	{ key: 'b', width: 4, height: 1 },
	{ key: 'c', width: 'fill', height: 1 },
	{ key: 'd', width: 'full', height: 1 },
];

function Dashboard() {
	const [ current, setCurrent ] = useState( layout );

	return (
		<DashboardGrid
			layout={ current }
			columns={ 6 }
			editMode
			onChangeLayout={ setCurrent }
		>
			<div key="a">Tile A</div>
			<div key="b">Tile B</div>
			<div key="c">Tile C</div>
			<div key="d">Tile D</div>
		</DashboardGrid>
	);
}

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 grid without explicit placement and fall through CSS Grid's auto-flow.

Layout model

interface DashboardGridLayoutItem {
	key: string; // matches child key
	width?: number | 'fill' | 'full'; // column span (see below)
	height?: number; // rows to span
	order?: number; // lower values render first (responsive mode)
}

width is a discriminated value:

• number: span that many columns (clamped to the grid's column count).
• 'fill': fill the remaining columns in the current row.
• 'full': span every column (grid-column: 1 / -1), forcing a row break.

'fill' is resolved per-row against the remaining free space.

Props

DashboardGrid forwards refs to its root <div>, and standard <div> 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

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:

Modes

Fixed columns

<DashboardGrid layout={ layout } columns={ 12 }>
	{ children }
</DashboardGrid>

Responsive

Columns are computed from container width using minColumnWidth as the lower bound per column. A ResizeObserver recomputes on container resize.

<DashboardGrid layout={ layout } minColumnWidth={ 240 }>
	{ children }
</DashboardGrid>

In responsive mode, layout items can provide an order to control display order independently of array position.

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 <DragOverlay>.
• 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

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 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 (MIT). Once native support lands across browsers, the polyfill can be removed without any public API change.

Usage

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 (
		<DashboardLanes
			layout={ current }
			columns={ 4 }
			editMode
			onChangeLayout={ setCurrent }
		>
			<Tile key="a">A</Tile>
			<Tile key="hero">Hero (spans 2 lanes)</Tile>
			<Tile key="b">B</Tile>
			<Tile key="c">C</Tile>
		</DashboardLanes>
	);
}

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

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

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

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

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:

const tiles = useMemo(
	() => layout.map( ( item ) => <Tile key={ item.key }>...</Tile> ),
	[ layout ]
);

return (
	<DashboardLanes layout={ layout } editMode onPreviewLayout={ ... }>
		{ tiles }
	</DashboardLanes>
);

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

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

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 <DndContext> for the resize gesture is internal to the handle wrapper; consumers do not need to mount their own.

import { Icon } from '@wordpress/ui';
import { resizeCornerNE } from '@wordpress/icons';

function CustomResizeHandle( {
	ref,
	listeners,
	attributes,
	verticalResizable,
} ) {
	return (
		<div
			ref={ ref }
			{ ...listeners }
			{ ...attributes }
			style={ {
				position: 'absolute',
				bottom: 4,
				insetInlineEnd: 4,
				cursor: verticalResizable ? 'nwse-resize' : 'ew-resize',
			} }
		>
			<Icon icon={ resizeCornerNE } size={ 16 } />
		</div>
	);
}

<DashboardGrid
	layout={ layout }
	editMode
	renderResizeHandle={ CustomResizeHandle }
>
	{ tiles }
</DashboardGrid>;

The component receives:

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

While a tile is being dragged, dnd-kit clones it into a <DragOverlay> 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:

import { DashboardGrid } from '@wordpress/grid';
import type { DragPreviewRenderProps } from '@wordpress/grid';

function DragPreview( { children }: DragPreviewRenderProps ) {
	return (
		<div className="my-tile-while-dragging">
			{ children }
		</div>
	);
}

<DashboardGrid
	layout={ layout }
	editMode
	renderDragPreview={ DragPreview }
>
	{ tiles }
</DashboardGrid>;

The component receives:

For token-only tweaks (lift scale, placeholder opacity, outline color, placeholder radius), prefer the CSS variables below; reach for renderDragPreview only when the dragged state needs markup the persistent tile does not have.

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.

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 and used by WordPress 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.