> ## Documentation Index
> Fetch the complete documentation index at: https://dnd-grid.blode.md/llms.txt
> Use this file to discover all available pages before exploring further.

# DndGrid

## Import

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

<Note>
  Need a headless wrapper? Use [`useDndGrid`](/hooks/use-dnd-grid) 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`.
</Note>

## Props

### Core props

<ResponseField name="layout" type="Layout" default="[]">
  Grid layout state (position and size per item). Missing entries are derived
  from children (with a dev warning).
</ResponseField>

<ResponseField name="children" type="ReactNode" required>
  Grid items; each child `key` must match a layout `id`.
</ResponseField>

### Measurement

<ResponseField name="width" type="number">
  Optional container width in pixels. When provided, measurement is skipped.
</ResponseField>

<ResponseField name="measureBeforeMount" type="boolean" default="true">
  Delay rendering until the container width is measured.
</ResponseField>

<ResponseField name="initialWidth" type="number" default="1280">
  Width used before measurement when rendering early.
</ResponseField>

<ResponseField name="containerProps" type="HTMLAttributes<HTMLDivElement>">
  Props applied to the measurement wrapper.
</ResponseField>

### Grid configuration

<ResponseField name="cols" type="number" default="12">
  Number of columns.
</ResponseField>

<ResponseField name="rowHeight" type="number" default="150">
  Row height in pixels.
</ResponseField>

<ResponseField
  name="gap"
  type="number | { top: number; right: number; bottom: number; left: number }"
  default="10"
>
  Gap between items. Use a number or `{ top, right, bottom, left }`.
</ResponseField>

<ResponseField
  name="containerPadding"
  type="number | { top: number; right: number; bottom: number; left: number } | null"
  default="null"
>
  Container padding. Use a number or `{ top, right, bottom, left }`. If null,
  uses the gap value.
</ResponseField>

<ResponseField name="autoSize" type="boolean" default="true">
  Resize container height to fit content.
</ResponseField>

<ResponseField name="maxRows" type="number" default="Infinity">
  Maximum rows.
</ResponseField>

### Behaviour

<ResponseField name="draggable" type="boolean" default="true">
  Enable dragging for all items. Can be overridden per item.
</ResponseField>

<ResponseField name="resizable" type="boolean" default="true">
  Enable resizing for all items. Can be overridden per item.
</ResponseField>

<ResponseField
  name="autoScroll"
  type="boolean | AutoScrollOptions"
  default="true"
>
  Auto-scroll near scroll edges. Use `true` for defaults or pass options.
</ResponseField>

<ResponseField name="bounded" type="boolean" default="false">
  Keep items within bounds during drag.
</ResponseField>

<ResponseField name="compactor" type="Compactor">
  Compaction strategy and collision behaviour.
</ResponseField>

<ResponseField name="constraints" type="LayoutConstraint[]">
  Drag and resize constraints. Defaults to `defaultConstraints`.
</ResponseField>

<ResponseField name="validation" type="boolean" default="true in dev, false in prod">
  Validate layouts at runtime with Zod. Disable to avoid extra work in hot paths.
</ResponseField>

<ResponseField name="callbackThrottle" type="number | { 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.
</ResponseField>

### Motion

<ResponseField name="animationConfig" type="AnimationConfig">
  Configure spring and shadow animations for drag, resize, and settling.
</ResponseField>

<ResponseField name="reducedMotion" type="ReducedMotionSetting | boolean">
  Motion preference override. Use `"system"` to respect
  `prefers-reduced-motion`.
</ResponseField>

### Accessibility

<ResponseField name="liveAnnouncements" type="LiveAnnouncementsOptions | false">
  Configure aria-live announcements for drag, resize, and focus. Pass `false` to
  disable.
</ResponseField>

<ResponseField name="aria-label" type="string">
  Accessible label for the grid container.
</ResponseField>

<ResponseField name="aria-labelledby" type="string">
  ID of the element that labels the grid.
</ResponseField>

<ResponseField name="aria-describedby" type="string">
  ID of the element that describes the grid.
</ResponseField>

### Drag configuration

<ResponseField name="dragHandle" type="string">
  Selector for elements that start a drag.
</ResponseField>

<ResponseField name="dragCancel" type="string">
  Selector for elements that cancel a drag.
</ResponseField>

<ResponseField name="dragTouchDelayDuration" type="number" default="250">
  Touch delay in milliseconds.
</ResponseField>

### Resize configuration

<ResponseField name="resizeHandles" type="ResizeHandleAxis[]" default='["se"]'>
  Edges and corners that show resize handles.
</ResponseField>

<ResponseField
  name="resizeHandle"
  type="ReactElement | ((axis, ref) => ReactElement)"
>
  Custom resize handle component.
</ResponseField>

### Drop configuration

Drop behavior is enabled when you provide `onDrop` or `onDropDragOver`.

<ResponseField name="droppingItem" type="Partial<LayoutItem>">
  Defaults for the dropped item.
</ResponseField>

### Transform

<ResponseField name="transformScale" type="number" default="1">
  Scale factor for CSS transforms.
</ResponseField>

### Styling

<ResponseField name="className" type="string">
  Extra CSS class for the container.
</ResponseField>

<ResponseField name="style" type="CSSProperties">
  Inline styles for the container.
</ResponseField>

<ResponseField name="slotProps" type="SlotProps">
  Customize className and style for items, placeholders, and resize handles.
</ResponseField>

<ResponseField name="innerRef" type="Ref<HTMLDivElement>">
  Ref to the container element.
</ResponseField>

## 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. |