@dnd-grid/react

@dnd-grid/react

A drag-and-drop (DnD), resizable grid layout with responsive breakpoints for React.

Installation

npm install @dnd-grid/react

Usage

import { useState } from "react";
import { DndGrid, type Layout } from "@dnd-grid/react";
import "@dnd-grid/react/styles.css";

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

function MyGrid() {
  const [currentLayout, setLayout] = useState(layout);

  return (
    <DndGrid
      layout={currentLayout}
      cols={12}
      rowHeight={30}
      onLayoutChange={(newLayout) => setLayout(newLayout)}
    >
      <div key="a">A</div>
      <div key="b">B</div>
      <div key="c">C</div>
    </DndGrid>
  );
}

Headless usage (advanced)

DndGrid is the recommended default. If you need a custom wrapper or want to control item rendering, use the headless useDndGrid hook and render GridItem manually.

Docs: https://dnd-grid.com/docs/hooks/use-dnd-grid

Auto width by default

DndGrid and ResponsiveDndGrid measure container width with ResizeObserver. Use containerProps to style the measurement wrapper, and measureBeforeMount / initialWidth to control the first render.

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

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

function MyGrid() {
  return (
    <DndGrid
      layout={layout}
      cols={12}
      rowHeight={30}
      containerProps={{ className: "w-full", style: { maxWidth: 600 } }}
    >
      <div key="a">A</div>
      <div key="b">B</div>
    </DndGrid>
  );
}

Explicit width (when you already have it)

If you already measure width (SSR or custom measurement), pass the width directly:

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

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

function MyGrid() {
  const { width, containerRef, mounted } = useContainerWidth({
    measureBeforeMount: true,
    initialWidth: 600,
  });

  return (
    <div ref={containerRef} className="w-full" style={{ maxWidth: 600 }}>
      {mounted && width > 0 && (
        <DndGrid
          layout={layout}
          cols={12}
          rowHeight={30}
          width={width}
        >
          <div key="a">A</div>
          <div key="b">B</div>
        </DndGrid>
      )}
    </div>
  );
}

Features

• 100% React - no jQuery
• Compatible with server-rendered apps
• Drag-and-drop widgets
• Resizable widgets
• Auto-scroll near edges while dragging
• State-aware styling via data attributes and item hooks
• Static widgets
• Configurable packing: horizontal, vertical, or off
• Bounds checking for dragging and resizing
• Widgets may be added or removed without rebuilding grid
• Layout can be serialised and restored
• Grid items placed using CSS transforms

Props

Prop	Type	Default	Description
children	ReactNode	required	Grid items; each child key must match a layout id.
layout	Layout	[]	Array of layout items; missing entries are derived from children (dev warning).
width	number	undefined	Optional container width in pixels. When provided, measurement is skipped.
measureBeforeMount	boolean	true	Delay rendering until the container width is measured.
initialWidth	number	1280	Width used before measurement when rendering early.
containerProps	HTMLAttributes<HTMLDivElement>	undefined	Props applied to the measurement wrapper.
cols	number	12	Number of columns
rowHeight	number	150	Height of a row in pixels
autoSize	boolean	true	Auto-size the container height
maxRows	number	Infinity	Maximum number of rows
gap	number | { top: number; right: number; bottom: number; left: number }	10	Gap around items
containerPadding	number | { top: number; right: number; bottom: number; left: number } | null	null	Container padding (null uses gap)
className	string	""	Extra class for the grid container
style	CSSProperties	{}	Inline styles for the grid container
draggable	boolean	true	Enable dragging
resizable	boolean	true	Enable resizing
autoScroll	boolean | AutoScrollOptions	true	Auto-scroll when dragging near scroll edges
bounded	boolean	false	Keep items within container bounds
compactor	Compactor	verticalCompactor	Compaction strategy
constraints	LayoutConstraint[]	defaultConstraints	Constraints applied during drag/resize
validation	boolean	true in dev, false in prod	Validate layouts at runtime with Zod
callbackThrottle	number | { drag?: number; resize?: number }	undefined	Throttle onDrag and onResize callbacks
animationConfig	AnimationConfig	default config	Configure spring and shadow animations
reducedMotion	ReducedMotionSetting | boolean	"system"	Motion preference override
resizeHandles	ResizeHandleAxis[]	["se"]	Resize handle positions
resizeHandle	ReactElement | ((axis, ref) => ReactElement)	undefined	Custom resize handle component
transformScale	number	1	Scale factor for CSS transforms
dragTouchDelayDuration	number	250	Touch delay before drag starts (ms)
dragHandle	string	""	Selector for drag handles
dragCancel	string	""	Selector for elements that cancel drag
droppingItem	Partial<LayoutItem>	{ id: "__dropping-elem__", w: 1, h: 1 }	Defaults for the dropping placeholder
slotProps	SlotProps	undefined	Slot styling for items, placeholders, and handles
liveAnnouncements	LiveAnnouncementsOptions | false	enabled	Configure aria-live announcements or disable
innerRef	Ref<HTMLDivElement>	undefined	Ref to the container element
aria-label	string	undefined	Accessible label for the grid
aria-labelledby	string	undefined	ID(s) of labelling elements
aria-describedby	string	undefined	ID(s) of descriptive elements

Layout is provided via the layout prop; data-grid on children is not supported. Missing layout entries are derived from children (with a dev warning).

Drop behavior is enabled when you provide onDrop or onDropDragOver.

DndGrid renders role="grid" and assigns role="gridcell" plus row/column indices to items. Placeholders and static items are excluded from set indexing.

Responsive layouts

Use ResponsiveDndGrid for breakpoint-aware layouts:

import { ResponsiveDndGrid, type ResponsiveLayouts } from "@dnd-grid/react";

const layouts: ResponsiveLayouts = {
  lg: [{ id: "a", x: 0, y: 0, w: 3, h: 2 }],
  md: [{ id: "a", x: 0, y: 0, w: 4, h: 2 }],
};

function ResponsiveGrid() {
  return (
    <ResponsiveDndGrid
      layouts={layouts}
      gap={{ lg: 16, md: { top: 12, right: 16, bottom: 12, left: 16 } }}
      containerPadding={16}
    >
      <div key="a">A</div>
      <div key="b">B</div>
    </ResponsiveDndGrid>
  );
}

For custom wrappers or manual width control, compose useDndGridResponsiveLayout with DndGrid.

Layout item

Each item in the layout array has these properties:

interface LayoutItem {
  id: string;     // Unique identifier
  x: number;      // X position in grid units
  y: number;      // Y position in grid units
  w: number;      // Width in grid units
  h: number;      // Height in grid units
  minW?: number;  // Minimum width
  maxW?: number;  // Maximum width
  minH?: number;  // Minimum height
  maxH?: number;  // Maximum height
  data?: TData;   // Optional metadata
  resizeHandles?: ResizeHandleAxis[]; // Override resize handle positions
  constraints?: LayoutConstraint[]; // Per-item constraints
  static?: boolean;     // Cannot be moved or resized
  draggable?: boolean; // Override grid draggable
  resizable?: boolean; // Override grid resizable
  bounded?: boolean;   // Override grid bounded
}

Styles

The default stylesheet ships as layout + theme layers. Import the combined file, or split them as needed:

import "@dnd-grid/react/styles.css";

import "@dnd-grid/react/base.css";
import "@dnd-grid/react/theme.css";

Theme variables are exposed as CSS custom properties:

:root {
  --dnd-grid-scale: 1;
  --dnd-grid-radius: 24px;
  --dnd-grid-placeholder-bg: rgba(0, 0, 0, 0.012);
  --dnd-grid-placeholder-shadow: inset 0 2px 4px rgba(0, 0, 0, 0.06);
  --dnd-grid-handle-size: 16px;
  --dnd-grid-handle-bg: rgb(255, 255, 255);
  --dnd-grid-handle-shadow: 0 0 1px 1px rgba(0, 0, 0, 0.06),
    0 9px 9px rgba(0, 0, 0, 0.04),
    0 5.83333px 5.27083px rgba(0, 0, 0, 0.03),
    0 3.46667px 2.86667px rgba(0, 0, 0, 0.024),
    0 1.8px 1.4625px rgba(0, 0, 0, 0.02),
    0 0.733333px 0.733333px rgba(0, 0, 0, 0.016);
  --dnd-grid-transition-duration: 200ms;
  --dnd-grid-transition-easing: cubic-bezier(0.2, 0, 0, 1);
}

Compactors

Compactors control how items are packed after drag/resize. You can use the built-ins or provide your own:

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

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

Constraints

Constraints let you enforce rules during drag/resize:

import { defaultConstraints, aspectRatio, gridBounds } from "@dnd-grid/react";

<DndGrid constraints={[gridBounds, aspectRatio(16 / 9)]} />;

Item state hook

Read the layout item and interaction state from within a child component:

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

function Card() {
  const { item, state } = useDndGridItemState();
  return (
    <div className={state.resizing ? "is-resizing" : ""}>
      Item {item.id}
    </div>
  );
}

The hook must be used inside a DndGrid item (it throws if rendered elsewhere).

External drag sources

If you manage drag state outside of the grid (for example with @dnd-kit), use the grid handle to drive the dropping placeholder and commit the drop:

const gridRef = useRef<DndGridHandle>(null);

const handleMove = (clientX: number, clientY: number) => {
  gridRef.current?.handleExternalDrag({ clientX, clientY });
};

const handleDrop = (clientX: number, clientY: number, event?: Event) => {
  gridRef.current?.handleExternalDrag({
    clientX,
    clientY,
    event,
    type: "drop",
  });
};

const handleCancel = (clientX: number, clientY: number, event?: Event) => {
  gridRef.current?.handleExternalDrag({
    clientX,
    clientY,
    event,
    type: "cancel",
  });
};

Use onDropDragOver to override the dropping placeholder size while dragging. If your drag library exposes a native event, pass it via event instead of generating one.

Callbacks

Callback	Type	Description
onLayoutChange	(layout: Layout) => void	Called when layout changes
onDragStart	(event: GridDragEvent) => void	Called when drag starts
onDrag	(event: GridDragEvent) => void	Called during drag
onDragEnd	(event: GridDragEvent) => void	Called when drag ends
onResizeStart	(event: GridResizeEvent) => void	Called when resize starts
onResize	(event: GridResizeEvent) => void	Called during resize
onResizeEnd	(event: GridResizeEvent) => void	Called when resize ends
onDrop	(layout, item, e) => void	Called when item is dropped
onDropDragOver	(e) => { w?: number; h?: number } | false	Customise dropping item

CSS classes

Common CSS classes include:

• .dnd-grid - Grid container
• .dnd-grid-item - Grid item
• .dnd-grid-item-content - Non-placeholder grid item
• .dnd-grid-placeholder - Placeholder during drag/resize
• .dnd-draggable - Draggable item
• .dnd-draggable-dragging - Item being dragged
• .resizing - Item currently being resized
• .static - Static (locked) item
• .dnd-grid-animating - Item settling after drag
• .dropping - Dropping placeholder item
• .dnd-grid-resize-handle - Resize handle element
• body.dnd-grid-dragging - Global dragging state
• body.dnd-grid-resizing - Global resizing state

Data attributes

The grid sets data-* attributes for stateful styling:

• data-dnd-grid on the container
• data-dnd-grid-live-region on the aria-live element
• data-dnd-grid-item on each item
• data-dnd-grid-item-id on each item
• data-dnd-grid-handle and data-handle-axis on resize handles
• data-dragging, data-resizing, data-settling, data-disabled, data-draggable, data-resizable on items when true

[data-dnd-grid-item][data-resizing] {
  z-index: 10;
}

[data-dnd-grid-handle][data-handle-axis="sw"] {
  cursor: sw-resize;
}

Acknowledgements

This project is based on react-grid-layout by Samuel Reed (STRML). The original project provided the foundation for the grid layout algorithms and core functionality.

Licence

MIT Licence - Copyright (c) 2025 Matthew Blode