DndGrid

Main grid layout component.

Import

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

Need a headless wrapper? Use useDndGrid to build your own container while keeping the same drag/resize behavior. For breakpoint layouts, use ResponsiveDndGrid. If you already have a measured width, pass width.

Props

Core props

layoutLayoutDefault: []

Grid layout state (position and size per item). Missing entries are derived from children (with a dev warning).

childrenReactNoderequired

Grid items; each child key must match a layout id.

Measurement

widthnumber

Optional container width in pixels. When provided, measurement is skipped.

measureBeforeMountbooleanDefault: true

Delay rendering until the container width is measured.

initialWidthnumberDefault: 1280

Width used before measurement when rendering early.

containerPropsHTMLAttributes<HTMLDivElement>

Props applied to the measurement wrapper.

Grid configuration

colsnumberDefault: 12

Number of columns.

rowHeightnumberDefault: 150

Row height in pixels.

gapnumber | { top: number; right: number; bottom: number; left: number }Default: 10

Gap between items. Use a number or { top, right, bottom, left }.

containerPaddingnumber | { top: number; right: number; bottom: number; left: number } | nullDefault: null

Container padding. Use a number or { top, right, bottom, left }. If null, uses the gap value.

autoSizebooleanDefault: true

Resize container height to fit content.

maxRowsnumberDefault: Infinity

Maximum rows.

Behaviour

draggablebooleanDefault: true

Enable dragging for all items. Can be overridden per item.

resizablebooleanDefault: true

Enable resizing for all items. Can be overridden per item.

autoScrollboolean | AutoScrollOptionsDefault: true

Auto-scroll near scroll edges. Use true for defaults or pass options.

boundedbooleanDefault: false

Keep items within bounds during drag.

compactorCompactor

Compaction strategy and collision behaviour.

constraintsLayoutConstraint[]

Drag and resize constraints. Defaults to defaultConstraints.

validationbooleanDefault: true in dev, false in prod

Validate layouts at runtime with Zod. Disable to avoid extra work in hot paths.

callbackThrottlenumber | { drag?: number; resize?: number }

Throttle onDrag and onResize callbacks in milliseconds. Pass a number to apply to both, or an object for per-callback control.

Motion

animationConfigAnimationConfig

Configure spring and shadow animations for drag, resize, and settling.

reducedMotionReducedMotionSetting | boolean

Motion preference override. Use "system" to respect prefers-reduced-motion.

Accessibility

liveAnnouncementsLiveAnnouncementsOptions | false

Configure aria-live announcements for drag, resize, and focus. Pass false to disable.

aria-labelstring

Accessible label for the grid container.

aria-labelledbystring

ID of the element that labels the grid.

aria-describedbystring

ID of the element that describes the grid.

Drag configuration

dragHandlestring

Selector for elements that start a drag.

dragCancelstring

Selector for elements that cancel a drag.

dragTouchDelayDurationnumberDefault: 250

Touch delay in milliseconds.

Resize configuration

resizeHandlesResizeHandleAxis[]Default: ["se"]

Edges and corners that show resize handles.

resizeHandleReactElement | ((axis, ref) => ReactElement)

Custom resize handle component.

Drop configuration

Drop behavior is enabled when you provide onDrop or onDropDragOver.

droppingItemPartial<LayoutItem>

Defaults for the dropped item.

Transform

transformScalenumberDefault: 1

Scale factor for CSS transforms.

Styling

classNamestring

Extra CSS class for the container.

styleCSSProperties

Inline styles for the container.

slotPropsSlotProps

Customize className and style for items, placeholders, and resize handles.

innerRefRef<HTMLDivElement>

Ref to the container element.

Callbacks

Callback	Description
`onLayoutChange`	Fires when the layout changes.
`onDragStart`	Fires when dragging starts.
`onDrag`	Fires while dragging.
`onDragEnd`	Fires when dragging ends.
`onResizeStart`	Fires when resizing starts.
`onResize`	Fires while resizing.
`onResizeEnd`	Fires when resizing ends.
`onDrop`	Fires when an external item is dropped.
`onDropDragOver`	Fires when an external item is dragged over the grid.