API overview

API reference for dnd-grid.

Exports

Common exports:

import {
  DndGrid,
  ResponsiveDndGrid,
  GridItem,
  ResizeHandle,
  useContainerWidth,
  useDndGrid,
  useDndGridResponsiveLayout,
  useDndGridItemState,
  useOptionalDndGridItemState,
  useReducedMotion,
  useEdgeScroll,
  createLayoutEngine,
  verticalCompactor,
  defaultConstraints,
  layoutSchema,
  layoutItemSchema,
  validateLayout,
  type Compactor,
  type GridDragEvent,
  type GridResizeEvent,
  type LayoutConstraint,
  type Layout,
  type LayoutItem,
  type ResponsiveLayouts,
} from "@dnd-grid/react";

Components

Component	Description
`DndGrid`	Main grid layout component
`ResponsiveDndGrid`	Breakpoint-aware responsive grid

Most apps should start with DndGrid for single-layout grids and ResponsiveDndGrid for breakpoint layouts. Use useDndGrid when you need a custom wrapper or want to control rendering. Both components measure their container width automatically (or accept a width prop when you already know it).

Also exported: GridItem and ResizeHandle.

Hooks

Hook	Description
`useContainerWidth`	Measure container width with ResizeObserver
`useDndGrid`	Headless hook for building custom grid wrappers
`useDndGridResponsiveLayout`	Manage responsive breakpoints + layout state
`useDndGridItemState`	Access item layout and interaction state
`useEdgeScroll`	Auto-scroll while dragging near scroll edges

Types

Type	Description
`Layout`	Array of layout items (`LayoutItem[]`)
`LayoutItem`	Position and size of a single grid item
`ResponsiveLayouts`	Breakpoint → layout map
`Compactor`	Pluggable compaction strategy
`LayoutConstraint`	Drag/resize constraint definition
`GridDragEvent`	Event object for drag callbacks
`GridResizeEvent`	Event object for resize callbacks

Additional exports

@dnd-grid/react also exports:

useOptionalDndGridItemState and useReducedMotion
createLayoutEngine and layout engine types for headless usage

Runtime validation

layoutSchema, layoutItemSchema, and validateLayout use Zod to validate layouts at runtime. DndGrid and useDndGrid also expose a validation prop (default: enabled in dev, disabled in production) to fail fast on bad layouts. Validation adds runtime work and bundle weight, so keep it off in hot paths if you do not need it.

CSS classes

Common classes you can target:

Class	Element
`.dnd-grid`	Grid container
`.dnd-grid-item`	Each grid item
`.dnd-grid-item-content`	Non-placeholder grid items
`.dnd-grid-placeholder`	Placeholder during drag/resize
`.dnd-draggable-dragging`	Item currently being dragged
`.resizing`	Item currently being resized

Quick reference

Essential props

<DndGrid
  layout={layout}
  cols={12}
  rowHeight={150}
  onLayoutChange={(layout) => {}}
>
  {children}
</DndGrid>

<ResponsiveDndGrid
  layouts={layouts}
  breakpoints={{ lg: 1200, md: 996, sm: 768, xs: 480, xxs: 0 }}
  cols={{ lg: 12, md: 10, sm: 6, xs: 4, xxs: 2 }}
>
  {children}
</ResponsiveDndGrid>

Import styles

Import the required CSS:

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