# Callbacks (https://dnd-grid.blode.md/api-reference/callbacks)

## Overview

dnd-grid provides callbacks for drag, resize, drop, and layout changes.

## Callback signature

Drag and resize callbacks receive an event object:

```tsx
type GridDragEvent<TData = unknown> = {
  type: "dragStart" | "drag" | "dragEnd";
  layout: Layout<TData>;
  previousItem: LayoutItem<TData> | null | undefined;
  item: LayoutItem<TData> | null | undefined;
  placeholder: LayoutItem<TData> | null | undefined;
  event: Event;
  node: HTMLElement | null | undefined;
};

type GridResizeEvent<TData = unknown> = {
  type: "resizeStart" | "resize" | "resizeEnd";
  layout: Layout<TData>;
  previousItem: LayoutItem<TData> | null | undefined;
  item: LayoutItem<TData> | null | undefined;
  placeholder: LayoutItem<TData> | null | undefined;
  event: Event;
  node: HTMLElement | null | undefined;
  handle: ResizeHandleAxis;
};
```

## Layout change

<ResponseField name="onLayoutChange" type="(layout: Layout) => void">
  Fires whenever the layout changes. Use this to persist layout state.
</ResponseField>

## Drag callbacks

<ResponseField name="onDragStart" type="(event: GridDragEvent) => void">
  Fires when a drag operation begins.
</ResponseField>

<ResponseField name="onDrag" type="(event: GridDragEvent) => void">
  Fires continuously during drag.
</ResponseField>

<ResponseField name="onDragEnd" type="(event: GridDragEvent) => void">
  Fires when a drag operation ends.
</ResponseField>

## Resize callbacks

<ResponseField name="onResizeStart" type="(event: GridResizeEvent) => void">
  Fires when a resize operation begins.
</ResponseField>

<ResponseField name="onResize" type="(event: GridResizeEvent) => void">
  Fires continuously during resize.
</ResponseField>

<ResponseField name="onResizeEnd" type="(event: GridResizeEvent) => void">
  Fires when a resize operation ends.
</ResponseField>

## Drop callbacks

<ResponseField name="onDrop" type="(layout: Layout, item: LayoutItem | null | undefined, event: Event) => void">
  Fires when an external item is dropped onto the grid.
</ResponseField>

<ResponseField name="onDropDragOver" type="(event?: DragOverEvent) => { w?: number; h?: number } | false | null | undefined">
  Called when an external item is dragged over the grid. Return size or `false` to reject the drop.
</ResponseField>

## Performance

> [!WARNING]
> `onDrag` and `onResize` fire frequently. Avoid expensive work in these callbacks.

For expensive updates, prefer `onDragEnd` or `onResizeEnd`, or set
`callbackThrottle` on `DndGrid` to limit call frequency.

# DndGrid (https://dnd-grid.blode.md/api-reference/dnd-grid)

## Import

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

> [!NOTE]
> Need a headless wrapper? Use [`useDndGrid`](https://dnd-grid.blode.md/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`.

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

# Layout item (https://dnd-grid.blode.md/api-reference/layout-item)

## Layout type

`Layout<TData>` is an array of `LayoutItem<TData>` objects:

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

type CardData = { kind: "chart" | "text" };

const layout: Layout<CardData> = [
  { id: "a", x: 0, y: 0, w: 2, h: 2, data: { kind: "chart" } },
  { id: "b", x: 2, y: 0, w: 2, h: 2, data: { kind: "text" } },
];
```

## Properties

### Required

<ResponseField name="id" type="string" required>
  Unique id. Must match the child's `key`.
</ResponseField>

<ResponseField name="x" type="number" required>
  X position in grid units (0-based).
</ResponseField>

<ResponseField name="y" type="number" required>
  Y position in grid units (0-based).
</ResponseField>

<ResponseField name="w" type="number" required>
  Width in grid units.
</ResponseField>

<ResponseField name="h" type="number" required>
  Height in grid units.
</ResponseField>

### Optional

<ResponseField name="minW" type="number">
  Minimum width.
</ResponseField>

<ResponseField name="maxW" type="number">
  Maximum width.
</ResponseField>

<ResponseField name="minH" type="number">
  Minimum height.
</ResponseField>

<ResponseField name="maxH" type="number">
  Maximum height.
</ResponseField>

<ResponseField name="constraints" type="LayoutConstraint[]">
  Per-item drag and resize constraints.
</ResponseField>

<ResponseField name="static" type="boolean" default="false">
  If true, the item is locked.
</ResponseField>

<ResponseField name="draggable" type="boolean">
  Override grid drag setting.
</ResponseField>

<ResponseField name="resizable" type="boolean">
  Override grid resize setting.
</ResponseField>

<ResponseField name="bounded" type="boolean">
  Override grid bounded setting.
</ResponseField>

<ResponseField name="resizeHandles" type="ResizeHandleAxis[]">
  Override grid resize handles.
</ResponseField>

<ResponseField name="data" type="TData">
  Optional typed metadata for the item.
</ResponseField>

## Examples

### With size constraints

```tsx
const layout: Layout = [
  {
    id: "constrained",
    x: 0, y: 0, w: 4, h: 3,
    minW: 2, maxW: 8,
    minH: 2, maxH: 6,
  },
];
```

# API overview (https://dnd-grid.blode.md/api-reference/overview)

## Exports

Common exports:

```tsx
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`](https://dnd-grid.blode.md/api-reference/dnd-grid) | Main grid layout component |
| [`ResponsiveDndGrid`](https://dnd-grid.blode.md/api-reference/responsive-dnd-grid) | Breakpoint-aware responsive grid |

Most apps should start with `DndGrid` for single-layout grids and
`ResponsiveDndGrid` for breakpoint layouts. Use
[`useDndGrid`](https://dnd-grid.blode.md/hooks/use-dnd-grid) 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`](https://dnd-grid.blode.md/hooks/use-container-width) | Measure container width with ResizeObserver |
| [`useDndGrid`](https://dnd-grid.blode.md/hooks/use-dnd-grid) | Headless hook for building custom grid wrappers |
| [`useDndGridResponsiveLayout`](https://dnd-grid.blode.md/hooks/use-dnd-grid-responsive-layout) | Manage responsive breakpoints + layout state |
| [`useDndGridItemState`](https://dnd-grid.blode.md/hooks/use-dnd-grid-item-state) | Access item layout and interaction state |
| [`useEdgeScroll`](https://dnd-grid.blode.md/hooks/use-edge-scroll) | Auto-scroll while dragging near scroll edges |

## Types

| Type | Description |
|------|-------------|
| [`Layout`](https://dnd-grid.blode.md/api-reference/layout-item#layout) | Array of layout items (`LayoutItem[]`) |
| [`LayoutItem`](https://dnd-grid.blode.md/api-reference/layout-item) | 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

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

```tsx
<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:

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

# ResponsiveDndGrid (https://dnd-grid.blode.md/api-reference/responsive-dnd-grid)

## Import

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

> [!NOTE]
> Use `ResponsiveDndGrid` when you need breakpoint layouts. For a single layout,
>   use [`DndGrid`](https://dnd-grid.blode.md/api-reference/dnd-grid). If you already have a measured
>   width, pass `width` directly.

## Props

### Core props

<ResponseField name="layouts" type="ResponsiveLayouts">
  Breakpoint → layout map. Missing layouts are derived from the nearest larger
  breakpoint (default behavior).
</ResponseField>

<ResponseField name="children" type="ReactNode" required>
  Grid items; each child `key` must match a layout item `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 value used before measuring when rendering early.
</ResponseField>

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

### Responsive configuration

<ResponseField name="breakpoints" type="Breakpoints">
  Breakpoint map, defaults to `lg`, `md`, `sm`, `xs`, `xxs`.
</ResponseField>

<ResponseField name="cols" type="BreakpointCols">
  Column count per breakpoint.
</ResponseField>

<ResponseField name="gap" type="ResponsiveSpacing" default="10">
  Gap per breakpoint (number or spacing object).
</ResponseField>

<ResponseField
  name="containerPadding"
  type="ResponsiveSpacing | null"
  default="null"
>
  Padding per breakpoint (or `null` to use gap).
</ResponseField>

<ResponseField name="defaultLayouts" type="ResponsiveLayouts">
  Uncontrolled initial layouts per breakpoint.
</ResponseField>

<ResponseField name="compactor" type="Compactor">
  Compaction strategy used for layout generation and collisions.
</ResponseField>

<ResponseField name="missingLayoutStrategy" type='"derive" | "warn" | "error" | "empty"'>
  Control how missing breakpoint layouts are handled.
</ResponseField>

<ResponseField name="onBreakpointChange" type="(bp, cols) => void">
  Fires when the active breakpoint changes.
</ResponseField>

<ResponseField name="onLayoutsChange" type="(layouts) => void">
  Fires when any breakpoint layout changes.
</ResponseField>

<ResponseField name="onLayoutChange" type="(layout, layouts) => void">
  Fires when the active breakpoint layout changes.
</ResponseField>

<ResponseField name="onWidthChange" type="(width, gap, cols, padding) => void">
  Fires on width or breakpoint configuration changes.
</ResponseField>

### Grid configuration & behavior

`ResponsiveDndGrid` supports the same grid configuration, behavior, accessibility,
and styling props as [`DndGrid`](https://dnd-grid.blode.md/api-reference/dnd-grid) (e.g. `rowHeight`,
`draggable`, `resizable`, `autoSize`, `slotProps`, and callbacks).

# Compactors (https://dnd-grid.blode.md/concepts/compactors)

Compactors are pluggable strategies that determine how items pack when space
opens up and how collisions are resolved. Pass a `Compactor` to the `compactor`
prop on `DndGrid`, or use them with responsive layouts.

## Built-in compactors

| Compactor | Behavior |
|-----------|----------|
| `verticalCompactor` | Default. Packs items upward by row. |
| `horizontalCompactor` | Packs items left-to-right, wrapping to the next row. |
| `noCompactor` | Leaves items where they are, no packing. |
| `verticalOverlapCompactor` | Vertical mode but allows overlap. |
| `horizontalOverlapCompactor` | Horizontal mode but allows overlap. |
| `fastVerticalCompactor` | Faster vertical packing for large layouts. |
| `fastHorizontalCompactor` | Faster horizontal packing for large layouts. |
| `fastVerticalOverlapCompactor` | Fast vertical mode with overlap allowed. |
| `fastHorizontalOverlapCompactor` | Fast horizontal mode with overlap allowed. |

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

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

## Overlap and collision behavior

- `allowOverlap: true` skips collision resolution. Items can overlap freely.
- `preventCollision: true` blocks a move if it would collide with another item.

```tsx
import { verticalCompactor, verticalOverlapCompactor } from "@dnd-grid/react";

<DndGrid compactor={{ ...verticalCompactor, preventCollision: true }} />
<DndGrid compactor={verticalOverlapCompactor} />
```

## Helpers and custom compactors

A compactor has four fields: `type`, `allowOverlap`, `compact`, and `onMove`.
You can implement your own, or build on the helpers below:

- `compactItemVertical`
- `compactItemHorizontal`
- `resolveCompactionCollision`

```tsx
import { type Compactor, compactItemVertical } from "@dnd-grid/react";

const myCompactor: Compactor = {
  type: "vertical",
  allowOverlap: false,
  compact(layout, _cols) {
    // Reorder items by your own logic, then compact vertically.
    const sorted = [...layout];
    const out = sorted.map((item) => ({ ...item }));
    const compareWith = out.filter((item) => item.static);
    let maxY = 0;

    for (const item of out) {
      if (!item.static) {
        compactItemVertical(compareWith, item, out, maxY);
        maxY = Math.max(maxY, item.y + item.h);
        compareWith.push(item);
      }
    }

    return out;
  },
  onMove(layout, item, x, y) {
    return layout.map((entry) =>
      entry.id === item.id ? { ...entry, x, y, moved: true } : entry,
    );
  },
};
```

# Constraints (https://dnd-grid.blode.md/concepts/constraints)

Constraints are small functions that clamp item position and size during drag or
resize. They run in order: grid-level `constraints` first, then per-item
`constraints` on the `LayoutItem`.

## Built-in constraints

| Constraint | Description |
|------------|-------------|
| `gridBounds` | Keep items inside the grid bounds. |
| `minMaxSize` | Respect `minW`, `maxW`, `minH`, `maxH` on items. |
| `containerBounds` | Clamp movement to the visible container height. |
| `boundedX` | Clamp horizontal movement only. |
| `boundedY` | Clamp vertical movement only. |
| `aspectRatio(ratio)` | Maintain a width/height ratio while resizing. |
| `snapToGrid(stepX, stepY)` | Snap movement to grid steps. |
| `minSize(minW, minH)` | Enforce minimum size. |
| `maxSize(maxW, maxH)` | Enforce maximum size. |
| `defaultConstraints` | `[gridBounds, minMaxSize]`. |

## Using constraints

```tsx
import { useState } from "react";
import {
  DndGrid,
  type Layout,
  type LayoutConstraint,
  aspectRatio,
  defaultConstraints,
  snapToGrid,
} from "@dnd-grid/react";

const topBand: LayoutConstraint = {
  name: "topBand(2)",
  constrainPosition(item, x, y) {
    const maxY = Math.max(0, 2 - item.h);
    return { x, y: Math.min(y, maxY) };
  },
};

const layout: Layout = [
  { id: "snap", x: 0, y: 0, w: 4, h: 2 },
  { id: "ratio", x: 4, y: 0, w: 4, h: 2 },
  { id: "band", x: 8, y: 0, w: 4, h: 2, constraints: [topBand] },
];

const constraints = [
  ...defaultConstraints,
  snapToGrid(2, 1),
  aspectRatio(16 / 9),
];

export function ConstraintGrid() {
  const [currentLayout, setLayout] = useState(layout);
  return (
    <DndGrid
      layout={currentLayout}
      cols={12}
      rowHeight={40}
      constraints={constraints}
      onLayoutChange={setLayout}
    >
      {currentLayout.map((item) => (
        <div key={item.id}>{item.id}</div>
      ))}
    </DndGrid>
  );
}
```

## Writing custom constraints

A `LayoutConstraint` can implement either `constrainPosition`, `constrainSize`,
or both. The `ConstraintContext` provides grid metrics and the full layout.

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

const lockRightColumn: LayoutConstraint = {
  name: "lockRightColumn",
  constrainPosition(item, x, y, { cols }) {
    const maxX = Math.max(0, cols - item.w);
    return { x: Math.max(x, maxX), y };
  },
};
```

## Constraint utilities

If you are building your own drag interactions, you can apply the same rules
manually with the exported helpers.

```tsx
import {
  applyPositionConstraints,
  applySizeConstraints,
  defaultConstraints,
} from "@dnd-grid/react";

const position = applyPositionConstraints(
  defaultConstraints,
  item,
  nextX,
  nextY,
  context,
);

const size = applySizeConstraints(
  defaultConstraints,
  item,
  nextW,
  nextH,
  handle,
  context,
);
```

# Grid items (https://dnd-grid.blode.md/concepts/grid-items)

## Basic items

Each child of `DndGrid` is a grid item. The child's `key` must match the layout `id`.

```tsx
<DndGrid layout={layout}>
  <div key="a">Content A</div>
  <div key="b">Content B</div>
  <div key="c">Content C</div>
</DndGrid>
```

## Styling items

Grid items are absolutely positioned with transforms. Style your content directly.

```tsx
<DndGrid layout={layout}>
  <div key="widget" className="my-widget">
    <h2>Dashboard Widget</h2>
    <p>Widget content goes here</p>
  </div>
</DndGrid>
```

```css
.my-widget {
  background: white;
  border-radius: 8px;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
  padding: 16px;
  height: 100%;
  overflow: auto;
}
```

> [!NOTE]
> Use `height: 100%` to fill the allocated space.

## Item behaviour

Use per-item fields to lock items, constrain size, or override grid settings.

```tsx
const layout: Layout = [
  { id: "header", x: 0, y: 0, w: 12, h: 1, static: true },
  { id: "content", x: 0, y: 1, w: 8, h: 4, minW: 4, maxW: 10 },
  {
    id: "custom",
    x: 8,
    y: 1,
    w: 4,
    h: 4,
    draggable: false,
    resizable: true,
    bounded: true,
    resizeHandles: ["s", "e"],
  },
];
```

Resize handles support edges (`n`, `e`, `s`, `w`) and corners (`ne`, `nw`, `se`, `sw`).

## Custom components

Custom components must forward `ref`, `style`, `className`, and event handlers.

```tsx
import { forwardRef } from "react";

interface WidgetProps {
  title: string;
  children: React.ReactNode;
}

const Widget = forwardRef<HTMLDivElement, WidgetProps>(
  ({ title, children, ...props }, ref) => {
    return (
      <div ref={ref} {...props} className="widget">
        <h3>{title}</h3>
        {children}
      </div>
    );
  }
);

<DndGrid layout={layout}>
  <Widget key="a" title="Sales">
    <Chart data={salesData} />
  </Widget>
</DndGrid>
```

## Drag regions

Limit dragging to a handle or exclude specific elements:

```tsx
<DndGrid
  dragHandle=".drag-handle"
  dragCancel=".no-drag"
  layout={layout}
>
  <div key="a">
    <div className="drag-handle">Drag here</div>
    <button className="no-drag">Click me</button>
    <div>Content</div>
  </div>
</DndGrid>
```

# Layout (https://dnd-grid.blode.md/concepts/layout)

## The layout object

The layout is the grid state. It is an array of items with position and size.

```ts
import { type Layout } from "@dnd-grid/react";

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

### Properties

| Prop | Type | Description |
|------|------|-------------|
| `id` | `string` | Required. Unique id, must match the child's `key`. |
| `x` | `number` | Required. Column index (0-based). |
| `y` | `number` | Required. Row index (0-based). |
| `w` | `number` | Required. Width in columns. |
| `h` | `number` | Required. Height in rows. |
| `minW` | `number` | Minimum width. |
| `maxW` | `number` | Maximum width. |
| `minH` | `number` | Minimum height. |
| `maxH` | `number` | Maximum height. |
| `static` | `boolean` | If `true`, the item is locked. |
| `draggable` | `boolean` | Override grid drag setting. |
| `resizable` | `boolean` | Override grid resize setting. |

For the full `LayoutItem` shape (constraints, resize handles, `data`, and more),
see the [Layout item API reference](https://dnd-grid.blode.md/api-reference/layout-item).

## Grid system

The grid uses a column and row coordinate system.

- **Columns (`x`):** Count is set by `cols` (default 12).
- **Rows (`y`):** Rows grow downward; height is set by `rowHeight`.
- **Width (`w`):** Number of columns an item spans.
- **Height (`h`):** Number of rows an item spans.

## Compaction

Compaction controls how items pack when space opens up.

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

<DndGrid compactor={verticalCompactor} />
<DndGrid compactor={horizontalCompactor} />
<DndGrid compactor={noCompactor} />
```

## Collisions

Choose collision behaviour when items overlap.

- **Push (default):** The dragged item pushes others out of the way.
- **Prevent collision:** The dragged item is blocked by others.
- **Allow overlap:** Items can be placed on top of each other.

```tsx
import { verticalCompactor, verticalOverlapCompactor } from "@dnd-grid/react";

<DndGrid compactor={{ ...verticalCompactor, preventCollision: true }} />
<DndGrid compactor={verticalOverlapCompactor} />
```

## Persistence

The layout is JSON-serialisable, so saving it is straightforward.

```tsx
const onLayoutChange = (newLayout) => {
  localStorage.setItem("grid", JSON.stringify(newLayout));
};
```

# Styling (https://dnd-grid.blode.md/concepts/styling)

## Required styles

The `@dnd-grid/react/styles.css` file includes layout and interaction styles. Always import it.

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

## CSS variables

`dnd-grid` uses CSS variables for theming. Override them in global CSS or on a grid container.

```css
:root {
  --dnd-grid-radius: 24px;
  --dnd-grid-placeholder-bg: rgba(0, 0, 0, 0.05);
  --dnd-grid-handle-bg: #ffffff;
}
```

### Reference

| Variable | Default | Description |
| :--- | :--- | :--- |
| `--dnd-grid-radius` | `24px` | Border radius for grid items and the placeholder. |
| `--dnd-grid-placeholder-bg` | `rgba(0,0,0,0.012)` | Background colour of the drop placeholder. |
| `--dnd-grid-handle-bg` | `#ffffff` | Colour of the default resize handle. |

## Item styles

Grid items use `.dnd-grid-item` for layout. Non-placeholder items also include
`.dnd-grid-item-content` so you can target visuals without affecting the placeholder:

```css
.dnd-grid-item-content {
  background: white;
  border: 1px solid #e2e8f0;
  box-shadow: 0 1px 3px 0 rgba(0, 0, 0, 0.1);
}

.dnd-grid-item.dnd-draggable-dragging {
  box-shadow: 0 10px 15px -3px rgba(0, 0, 0, 0.1);
  z-index: 10;
}
```

## State classes

Use these classes for states and placeholders:

- `.dnd-draggable-dragging`: Item being dragged.
- `.resizing`: Item being resized.
- `.dnd-grid-placeholder`: Placeholder during drag/resize.
- `.is-hovered`: Hover state.

## Custom resize handles

Replace the handle UI with a custom component:

```tsx
<DndGrid resizeHandle={<div className="my-custom-handle" />} />
```

## Reduced motion

`DndGrid` respects `prefers-reduced-motion` for spring and WAAPI effects. You can
override the behavior with `reducedMotion`:

```tsx
<DndGrid reducedMotion="always" />
```

Accepted values:

- `"system"` (default): use the OS preference.
- `"always"`: disable motion.
- `"never"`: always allow motion.
- `true`/`false`: aliases for `"always"`/`"never"`.

To disable CSS transitions as well, set the transition variables in a media
query:

```css
@media (prefers-reduced-motion: reduce) {
  .dnd-grid {
    --dnd-grid-transition-duration: 0ms;
  }
}
```

## Animation config

Use `animationConfig` to tune spring behavior and drag shadow timings:

```tsx
<DndGrid
  animationConfig={{
    springs: {
      rotation: { stiffness: 120, damping: 12 },
      scale: { stiffness: 600, damping: 35 },
      position: { stiffness: 240, damping: 24 },
    },
    shadow: {
      dragStartDuration: 160,
      dragStopDuration: 120,
    },
  }}
/>
```

Disable springs or shadow animations entirely:

```tsx
<DndGrid
  animationConfig={{
    springs: { enabled: false },
    shadow: { enabled: false },
  }}
/>
```

# Allow overlap (https://dnd-grid.blode.md/examples/allow-overlap)

<div className="not-prose my-6 rounded-lg border border-zinc-200/70 bg-white/70 shadow-sm dark:border-white/10 dark:bg-white/5">
  <iframe
    title="Allow overlap preview"
    src="https://dnd-grid.com/examples/allow-overlap-example?embed=1"
    className="h-[640px] w-full"
    loading="lazy"
  />
</div>

[View source on GitHub](https://github.com/mblode/dnd-grid/blob/main/apps/web/examples/dnd-grid-allow-overlap-example.tsx)

## Installation

### CLI

```bash
npx shadcn@latest add https://dnd-grid.com/r/allow-overlap-example.json
```
### Manual

```bash
npm install @dnd-grid/react
```

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

```tsx title="components/dnd-grid-allow-overlap-example.tsx"
"use client";

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

const initialLayout: Layout = [
  { id: "a", x: 0, y: 0, w: 3, h: 2 },
  { id: "b", x: 1, y: 0, w: 3, h: 2 },
  { id: "c", x: 2, y: 1, w: 3, h: 2 },
  { id: "d", x: 6, y: 0, w: 3, h: 3 },
];

export function AllowOverlapExample() {
  const [layout, setLayout] = useState<Layout>(initialLayout);
  const [allowOverlap, setAllowOverlap] = useState(true);
  const compactor = allowOverlap ? verticalOverlapCompactor : verticalCompactor;

  return (
    <div>
      <button type="button" onClick={() => setAllowOverlap((prev) => !prev)}>
        {allowOverlap ? "Disable overlap" : "Enable overlap"}
      </button>

      <DndGrid
        layout={layout}
        cols={12}
        rowHeight={50}
        compactor={compactor}
        onLayoutChange={setLayout}
      >
        {layout.map((item) => (
          <div key={item.id} className="grid-item">
            {item.id}
          </div>
        ))}
      </DndGrid>
    </div>
  );
}
```

## Usage

```tsx
import { AllowOverlapExample } from "@/components/dnd-grid-allow-overlap-example";

export default function Page() {
  return <AllowOverlapExample />;
}
```

# Aspect ratio constraints (https://dnd-grid.blode.md/examples/aspect-ratio-constraints)

<div className="not-prose my-6 rounded-lg border border-zinc-200/70 bg-white/70 shadow-sm dark:border-white/10 dark:bg-white/5">
  <iframe
    title="Aspect ratio constraints preview"
    src="https://dnd-grid.com/examples/aspect-ratio-constraints-example?embed=1"
    className="h-[640px] w-full"
    loading="lazy"
  />
</div>

[View source on GitHub](https://github.com/mblode/dnd-grid/blob/main/apps/web/examples/dnd-grid-aspect-ratio-constraints-example.tsx)

## Installation

### CLI

```bash
npx shadcn@latest add https://dnd-grid.com/r/aspect-ratio-constraints-example.json
```
### Manual

```bash
npm install @dnd-grid/react
```

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

```tsx title="components/dnd-grid-aspect-ratio-constraints-example.tsx"
"use client";

import {
  applySizeConstraints,
  aspectRatio,
  type ConstraintContext,
  DndGrid,
  defaultConstraints,
  type Layout,
  useContainerWidth,
} from "@dnd-grid/react";
import * as React from "react";

const COLS = 12;
const ROW_HEIGHT = 50;
const GRID_SPACING = 10;

const ratio16x9 = aspectRatio(16 / 9);
const ratio1x1 = aspectRatio(1);

const baseLayout: Layout = [
  { id: "16:9", x: 0, y: 0, w: 6, h: 3, constraints: [ratio16x9] },
  { id: "1:1", x: 6, y: 0, w: 3, h: 3, constraints: [ratio1x1] },
  { id: "free", x: 9, y: 0, w: 3, h: 2 },
];

const createConstraintContext = (
  layout: Layout,
  containerWidth: number,
): ConstraintContext => ({
  cols: COLS,
  maxRows: Number.POSITIVE_INFINITY,
  containerWidth,
  containerHeight: 0,
  rowHeight: ROW_HEIGHT,
  gap: [GRID_SPACING, GRID_SPACING, GRID_SPACING, GRID_SPACING],
  containerPadding: [GRID_SPACING, GRID_SPACING, GRID_SPACING, GRID_SPACING],
  layout,
});

const applyInitialConstraints = (
  layout: Layout,
  containerWidth: number,
): Layout => {
  const context = createConstraintContext(layout, containerWidth);
  return layout.map((item) => {
    if (!item.constraints?.length) return item;
    const size = applySizeConstraints(
      defaultConstraints,
      item,
      item.w,
      item.h,
      "se",
      context,
    );
    if (size.w === item.w && size.h === item.h) return item;
    return { ...item, ...size };
  });
};

export function AspectRatioConstraintsExample() {
  const { width, containerRef, mounted } = useContainerWidth({
    measureBeforeMount: true,
  });
  const [layout, setLayout] = React.useState<Layout>(baseLayout);
  const [ready, setReady] = React.useState(false);

  React.useEffect(() => {
    if (!mounted || width <= 0 || ready) return;
    setLayout(applyInitialConstraints(baseLayout, width));
    setReady(true);
  }, [mounted, ready, width]);

  return (
    <div ref={containerRef}>
      {mounted && ready && (
        <DndGrid
          layout={layout}
          cols={COLS}
          rowHeight={ROW_HEIGHT}
          width={width}
          gap={GRID_SPACING}
          containerPadding={GRID_SPACING}
          onLayoutChange={setLayout}
        >
          {layout.map((item) => (
            <div key={item.id} className="grid-item">
              {item.id}
            </div>
          ))}
        </DndGrid>
      )}
    </div>
  );
}
```

## Usage

```tsx
import { AspectRatioConstraintsExample } from "@/components/dnd-grid-aspect-ratio-constraints-example";

export default function Page() {
  return <AspectRatioConstraintsExample />;
}
```

# Basic example (https://dnd-grid.blode.md/examples/basic)

<div className="not-prose my-6 rounded-lg border border-zinc-200/70 bg-white/70 shadow-sm dark:border-white/10 dark:bg-white/5">
  <iframe
    title="Basic example preview"
    src="https://dnd-grid.com/examples/basic-example?embed=1"
    className="h-[640px] w-full"
    loading="lazy"
  />
</div>

[View source on GitHub](https://github.com/mblode/dnd-grid/blob/main/apps/web/examples/dnd-grid-basic-example.tsx)

## Installation

### CLI

```bash
npx shadcn@latest add https://dnd-grid.com/r/basic-example.json
```
### Manual

```bash
npm install @dnd-grid/react
```

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

```tsx title="components/dnd-grid-basic-example.tsx"
"use client";

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

const initialLayout: Layout = [
  { id: "a", x: 0, y: 0, w: 3, h: 2 },
  { id: "b", x: 3, y: 0, w: 3, h: 2 },
  { id: "c", x: 6, y: 0, w: 3, h: 2 },
  { id: "d", x: 9, y: 0, w: 3, h: 2 },
];

export function BasicExample() {
  const [layout, setLayout] = useState<Layout>(initialLayout);

  return (
    <DndGrid
      layout={layout}
      cols={12}
      rowHeight={50}
      onLayoutChange={setLayout}
    >
      {layout.map((item) => (
        <div key={item.id} className="grid-item">
          {item.id}
        </div>
      ))}
    </DndGrid>
  );
}
```

## Usage

```tsx
import { BasicExample } from "@/components/dnd-grid-basic-example";

export default function Page() {
  return <BasicExample />;
}
```

# Bounded (https://dnd-grid.blode.md/examples/bounded)

<div className="not-prose my-6 rounded-lg border border-zinc-200/70 bg-white/70 shadow-sm dark:border-white/10 dark:bg-white/5">
  <iframe
    title="Bounded preview"
    src="https://dnd-grid.com/examples/bounded-example?embed=1"
    className="h-[640px] w-full"
    loading="lazy"
  />
</div>

[View source on GitHub](https://github.com/mblode/dnd-grid/blob/main/apps/web/examples/dnd-grid-bounded-example.tsx)

## Installation

### CLI

```bash
npx shadcn@latest add https://dnd-grid.com/r/bounded-example.json
```
### Manual

```bash
npm install @dnd-grid/react
```

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

```tsx title="components/dnd-grid-bounded-example.tsx"
"use client";

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

const initialLayout: Layout = [0, 1, 2, 3, 4, 5].map((i) => ({
  id: i.toString(),
  x: (i * 2) % 12,
  y: Math.floor(i / 6) * 2,
  w: 2,
  h: 2,
}));

export function BoundedExample() {
  const [layout, setLayout] = useState<Layout>(initialLayout);

  return (
    <DndGrid
      layout={layout}
      cols={12}
      rowHeight={50}
      bounded
      onLayoutChange={setLayout}
    >
      {layout.map((item) => (
        <div key={item.id} className="grid-item">
          {item.id}
        </div>
      ))}
    </DndGrid>
  );
}
```

## Usage

```tsx
import { BoundedExample } from "@/components/dnd-grid-bounded-example";

export default function Page() {
  return <BoundedExample />;
}
```

# Compactor showcase (https://dnd-grid.blode.md/examples/compactor-showcase)

<div className="not-prose my-6 rounded-lg border border-zinc-200/70 bg-white/70 shadow-sm dark:border-white/10 dark:bg-white/5">
  <iframe
    title="Compactor showcase preview"
    src="https://dnd-grid.com/examples/compactor-showcase-example?embed=1"
    className="h-[640px] w-full"
    loading="lazy"
  />
</div>

[View source on GitHub](https://github.com/mblode/dnd-grid/blob/main/apps/web/examples/dnd-grid-compactor-showcase-example.tsx)

## Installation

### CLI

```bash
npx shadcn@latest add https://dnd-grid.com/r/compactor-showcase-example.json
```
### Manual

```bash
npm install @dnd-grid/react
```

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

```tsx title="components/dnd-grid-compactor-showcase-example.tsx"
"use client";

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

const initialLayout: Layout = [
  { id: "a", x: 0, y: 0, w: 2, h: 2 },
  { id: "b", x: 5, y: 0, w: 3, h: 2 },
  { id: "c", x: 9, y: 0, w: 2, h: 2 },
  { id: "d", x: 0, y: 4, w: 4, h: 2 },
  { id: "e", x: 6, y: 6, w: 3, h: 3 },
  { id: "f", x: 2, y: 9, w: 2, h: 2 },
];

const compactors = {
  vertical: verticalCompactor,
  horizontal: horizontalCompactor,
  none: noCompactor,
} as const;

type CompactorKey = keyof typeof compactors;

export function CompactorShowcaseExample() {
  const [layout, setLayout] = useState<Layout>(initialLayout);
  const [compactorKey, setCompactorKey] = useState<CompactorKey>("vertical");

  return (
    <div>
      <div style={{ display: "flex", gap: 8, marginBottom: 12 }}>
        {(
          [
            { id: "vertical", label: "Vertical" },
            { id: "horizontal", label: "Horizontal" },
            { id: "none", label: "None" },
          ] as const
        ).map((option) => (
          <button
            key={option.id}
            type="button"
            onClick={() => setCompactorKey(option.id)}
          >
            {option.label}
          </button>
        ))}
      </div>

      <DndGrid
        layout={layout}
        cols={12}
        rowHeight={50}
        compactor={compactors[compactorKey]}
        onLayoutChange={setLayout}
      >
        {layout.map((item) => (
          <div key={item.id} className="grid-item">
            {item.id}
          </div>
        ))}
      </DndGrid>
    </div>
  );
}
```

## Usage

```tsx
import { CompactorShowcaseExample } from "@/components/dnd-grid-compactor-showcase-example";

export default function Page() {
  return <CompactorShowcaseExample />;
}
```

# Constraints (https://dnd-grid.blode.md/examples/constraints)

<div className="not-prose my-6 rounded-lg border border-zinc-200/70 bg-white/70 shadow-sm dark:border-white/10 dark:bg-white/5">
  <iframe
    title="Constraints preview"
    src="https://dnd-grid.com/examples/constraints-example?embed=1"
    className="h-[640px] w-full"
    loading="lazy"
  />
</div>

[View source on GitHub](https://github.com/mblode/dnd-grid/blob/main/apps/web/examples/dnd-grid-constraints-example.tsx)

## Installation

### CLI

```bash
npx shadcn@latest add https://dnd-grid.com/r/constraints-example.json
```
### Manual

```bash
npm install @dnd-grid/react
```

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

```tsx title="components/dnd-grid-constraints-example.tsx"
"use client";

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

const topBandConstraint: LayoutConstraint = {
  name: "topBand(4)",
  constrainPosition(item, x, y) {
    const maxY = Math.max(0, 4 - item.h);
    return { x, y: Math.min(y, maxY) };
  },
};

const gridConstraints: LayoutConstraint[] = [
  ...defaultConstraints,
  snapToGrid(2, 1),
];

const initialLayout: Layout = [
  { id: "snap", x: 0, y: 0, w: 3, h: 2 },
  {
    id: "limits",
    x: 3,
    y: 0,
    w: 3,
    h: 2,
    minW: 2,
    maxW: 5,
    minH: 2,
    maxH: 4,
  },
  {
    id: "band",
    x: 6,
    y: 0,
    w: 3,
    h: 2,
    constraints: [topBandConstraint],
  },
];

export function ConstraintsExample() {
  const [layout, setLayout] = useState<Layout>(initialLayout);

  return (
    <DndGrid
      layout={layout}
      cols={12}
      rowHeight={50}
      constraints={gridConstraints}
      onLayoutChange={setLayout}
    >
      {layout.map((item) => (
        <div key={item.id} className="grid-item">
          {item.id}
        </div>
      ))}
    </DndGrid>
  );
}
```

## Usage

```tsx
import { ConstraintsExample } from "@/components/dnd-grid-constraints-example";

export default function Page() {
  return <ConstraintsExample />;
}
```

# Drag from outside (https://dnd-grid.blode.md/examples/drag-from-outside)

<div className="not-prose my-6 rounded-lg border border-zinc-200/70 bg-white/70 shadow-sm dark:border-white/10 dark:bg-white/5">
  <iframe
    title="Drag from outside preview"
    src="https://dnd-grid.com/examples/drag-from-outside-example?embed=1"
    className="h-[640px] w-full"
    loading="lazy"
  />
</div>

[View source on GitHub](https://github.com/mblode/dnd-grid/blob/main/apps/web/examples/dnd-grid-drag-from-outside-example.tsx)

## Installation

### CLI

```bash
npx shadcn@latest add https://dnd-grid.com/r/drag-from-outside-example.json
```
### Manual

```bash
npm install @dnd-grid/react
```

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

```tsx title="components/dnd-grid-drag-from-outside-example.tsx"
"use client";

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

type PaletteItem = {
  id: string;
  label: string;
  w: number;
  h: number;
};

const paletteItems: PaletteItem[] = [
  { id: "small", label: "Small (2x2)", w: 2, h: 2 },
  { id: "wide", label: "Wide (4x2)", w: 4, h: 2 },
  { id: "tall", label: "Tall (2x4)", w: 2, h: 4 },
];

const initialLayout: Layout = [
  { id: "a", x: 0, y: 0, w: 3, h: 2 },
  { id: "b", x: 3, y: 0, w: 3, h: 3 },
  { id: "c", x: 6, y: 0, w: 3, h: 2 },
  { id: "d", x: 9, y: 0, w: 3, h: 2 },
];

export function DragFromOutsideExample() {
  const [layout, setLayout] = useState<Layout>(initialLayout);
  const dragItemRef = useRef<PaletteItem | null>(null);
  const nextIdRef = useRef(1);

  const handleDropDragOver = () => {
    const active = dragItemRef.current;
    return active ? { w: active.w, h: active.h } : undefined;
  };

  const handleDrop = (_layout: Layout, item?: LayoutItem | null) => {
    if (!item) return;
    const nextId = `n${nextIdRef.current}`;
    nextIdRef.current += 1;
    setLayout((prev) => [
      ...prev,
      { id: nextId, x: item.x, y: item.y, w: item.w, h: item.h },
    ]);
  };

  return (
    <div>
      <div style={{ display: "flex", gap: 12, marginBottom: 12 }}>
        {paletteItems.map((palette) => (
          <button
            key={palette.id}
            type="button"
            draggable
            onDragStart={(event) => {
              dragItemRef.current = palette;
              event.dataTransfer.setData("text/plain", palette.id);
            }}
            style={{
              appearance: "none",
              background: "white",
              border: "1px solid #e5e7eb",
              padding: "6px 10px",
              borderRadius: "6px",
              fontSize: "12px",
              cursor: "grab",
            }}
          >
            {palette.label}
          </button>
        ))}
      </div>

      <DndGrid
        layout={layout}
        cols={12}
        rowHeight={50}
        onDrop={handleDrop}
        onDropDragOver={handleDropDragOver}
        onLayoutChange={setLayout}
      >
        {layout.map((item) => (
          <div key={item.id} className="grid-item">
            {item.id}
          </div>
        ))}
      </DndGrid>
    </div>
  );
}
```

## Usage

```tsx
import { DragFromOutsideExample } from "@/components/dnd-grid-drag-from-outside-example";

export default function Page() {
  return <DragFromOutsideExample />;
}
```

# Dynamic add/remove (https://dnd-grid.blode.md/examples/dynamic-add-remove)

<div className="not-prose my-6 rounded-lg border border-zinc-200/70 bg-white/70 shadow-sm dark:border-white/10 dark:bg-white/5">
  <iframe
    title="Dynamic add/remove preview"
    src="https://dnd-grid.com/examples/dynamic-add-remove-example?embed=1"
    className="h-[640px] w-full"
    loading="lazy"
  />
</div>

[View source on GitHub](https://github.com/mblode/dnd-grid/blob/main/apps/web/examples/dnd-grid-dynamic-add-remove-example.tsx)

## Installation

### CLI

```bash
npx shadcn@latest add https://dnd-grid.com/r/dynamic-add-remove-example.json
```
### Manual

```bash
npm install @dnd-grid/react
```

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

```tsx title="components/dnd-grid-dynamic-add-remove-example.tsx"
"use client";

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

const removeButtonStyle: CSSProperties = {
  position: "absolute",
  top: 6,
  right: 6,
  width: 22,
  height: 22,
  borderRadius: 9999,
  border: "1px solid #e5e7eb",
  background: "white",
  color: "#0f172a",
  display: "inline-flex",
  alignItems: "center",
  justifyContent: "center",
  fontSize: 12,
  lineHeight: "1",
  cursor: "pointer",
  boxShadow: "0 1px 2px rgba(15, 23, 42, 0.08)",
};

export function DynamicAddRemoveExample() {
  const [counter, setCounter] = useState(5);
  const [layout, setLayout] = useState<Layout>(
    [0, 1, 2, 3, 4].map((i) => ({
      id: i.toString(),
      x: (i * 2) % 12,
      y: 0,
      w: 2,
      h: 2,
    })),
  );

  const addItem = useCallback(() => {
    setLayout((prev) => {
      const position = findEmptyPosition(prev, { w: 2, h: 2 }, 12);

      return [
        ...prev,
        {
          id: `n${counter}`,
          ...position,
          w: 2,
          h: 2,
        },
      ];
    });
    setCounter((c) => c + 1);
  }, [counter]);

  const removeItem = useCallback((id: string) => {
    setLayout((prev) => prev.filter((item) => item.id !== id));
  }, []);

  const removeLastItem = useCallback(() => {
    setLayout((prev) => (prev.length > 0 ? prev.slice(0, -1) : prev));
  }, []);

  return (
    <div>
      <div style={{ display: "flex", gap: 8, marginBottom: 12 }}>
        <button type="button" onClick={addItem}>
          Add Item
        </button>
        <button
          type="button"
          onClick={removeLastItem}
          disabled={layout.length === 0}
        >
          Remove Last Item
        </button>
      </div>

      <DndGrid
        layout={layout}
        cols={12}
        rowHeight={50}
        dragCancel=".grid-item-remove"
        onLayoutChange={setLayout}
      >
        {layout.map((item) => (
          <div key={item.id} className="grid-item">
            <span>{item.id}</span>
            <button
              type="button"
              onClick={() => removeItem(item.id)}
              style={removeButtonStyle}
              className="grid-item-remove"
              aria-label={`Remove ${item.id}`}
              title="Remove"
            >
              x
            </button>
          </div>
        ))}
      </DndGrid>
    </div>
  );
}
```

## Usage

```tsx
import { DynamicAddRemoveExample } from "@/components/dnd-grid-dynamic-add-remove-example";

export default function Page() {
  return <DynamicAddRemoveExample />;
}
```

# Headless wrapper (https://dnd-grid.blode.md/examples/headless)

<div className="not-prose my-6 rounded-lg border border-zinc-200/70 bg-white/70 shadow-sm dark:border-white/10 dark:bg-white/5">
  <iframe
    title="Headless wrapper preview"
    src="https://dnd-grid.com/examples/headless-example?embed=1"
    className="h-[640px] w-full"
    loading="lazy"
  />
</div>

[View source on GitHub](https://github.com/mblode/dnd-grid/blob/main/apps/web/examples/dnd-grid-headless-example.tsx)

## Installation

### CLI

```bash
npx shadcn@latest add https://dnd-grid.com/r/headless-example.json
```
### Manual

```bash
npm install @dnd-grid/react
```

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

```tsx title="components/dnd-grid-headless-example.tsx"
"use client";

import {
  GridItem,
  type Layout,
  useContainerWidth,
  useDndGrid,
} from "@dnd-grid/react";
import * as React from "react";

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

export function HeadlessExample() {
  const [layout, setLayout] = React.useState(initialLayout);
  const { width, containerRef, mounted } = useContainerWidth({
    measureBeforeMount: true,
  });
  const children = layout.map((item) => (
    <div key={item.id} className="grid-item">
      {item.id}
    </div>
  ));

  const { gridProps, itemProps, liveRegionElement } = useDndGrid({
    layout,
    onLayoutChange: setLayout,
    cols: 12,
    rowHeight: 50,
    width,
    children,
  });

  const { ref: gridRef, ...restGridProps } = gridProps;
  const setGridRef = React.useCallback(
    (node: HTMLDivElement | null) => {
      containerRef.current = node;
      if (typeof gridRef === "function") {
        gridRef(node);
        return;
      }
      if (gridRef) {
        (gridRef as React.MutableRefObject<HTMLDivElement | null>).current =
          node;
      }
    },
    [containerRef, gridRef],
  );

  const droppingProps = itemProps.getDroppingItemProps();
  const placeholderProps = itemProps.getPlaceholderProps();

  return (
    <div className="space-y-2">
      <div className="text-xs text-zinc-500">Custom wrapper</div>
      <div {...restGridProps} ref={setGridRef}>
        {mounted && (
          <>
            {liveRegionElement}
            {React.Children.map(children, (child) => {
              const props = itemProps.getItemProps(child);
              return props ? <GridItem {...props} /> : null;
            })}
            {droppingProps && <GridItem {...droppingProps} />}
            {placeholderProps && <GridItem {...placeholderProps} />}
          </>
        )}
      </div>
    </div>
  );
}
```

## Usage

```tsx
import { HeadlessExample } from "@/components/dnd-grid-headless-example";

export default function Page() {
  return <HeadlessExample />;
}
```

# Kitchen sink (https://dnd-grid.blode.md/examples/kitchen-sink)

<div className="not-prose my-6 rounded-lg border border-zinc-200/70 bg-white/70 shadow-sm dark:border-white/10 dark:bg-white/5">
  <iframe
    title="Kitchen sink preview"
    src="https://dnd-grid.com/examples/kitchen-sink-example?embed=1"
    className="h-[640px] w-full"
    loading="lazy"
  />
</div>

[View source on GitHub](https://github.com/mblode/dnd-grid/blob/main/apps/web/examples/dnd-grid-kitchen-sink-example.tsx)

## Installation

### CLI

```bash
npx shadcn@latest add https://dnd-grid.com/r/kitchen-sink-example.json
```
### Manual

```bash
npm install @dnd-grid/react @dnd-kit/core
```

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

```tsx title="components/dnd-grid-kitchen-sink-example.tsx"
"use client";

import {
  DndGrid,
  type DndGrid as DndGridHandle,
  type Layout,
  type LayoutItem,
} from "@dnd-grid/react";
import {
  DndContext,
  type DragEndEvent,
  type DragMoveEvent,
  DragOverlay,
  type DragStartEvent,
  KeyboardSensor,
  MouseSensor,
  TouchSensor,
  useDraggable,
  useSensor,
  useSensors,
} from "@dnd-kit/core";
import { useCallback, useMemo, useRef, useState } from "react";

type PaletteItem = {
  id: string;
  title: string;
  w: number;
  h: number;
};

type GridItem = {
  id: string;
  title: string;
  w: number;
  h: number;
  x: number;
  y: number;
};

const paletteItems: PaletteItem[] = [
  { id: "text", title: "Text", w: 4, h: 4 },
  { id: "media", title: "Media", w: 4, h: 3 },
  { id: "cta", title: "CTA", w: 2, h: 2 },
  { id: "quote", title: "Quote", w: 3, h: 3 },
];

const initialItems: GridItem[] = [
  { id: "a", title: "Text", x: 0, y: 0, w: 4, h: 4 },
  { id: "b", title: "Media", x: 0, y: 4, w: 2, h: 3 },
  { id: "c", title: "CTA", x: 2, y: 4, w: 2, h: 2 },
  { id: "d", title: "Quote", x: 0, y: 7, w: 4, h: 3 },
];

const findEmptyPosition = ({
  layouts,
  newItemWidth,
  newItemHeight,
  gridWidth,
  gridHeight,
}: {
  layouts: Layout;
  newItemWidth: number;
  newItemHeight: number;
  gridWidth: number;
  gridHeight: number;
}): { x: number; y: number } => {
  const grid = Array.from({ length: gridHeight }, () =>
    Array.from({ length: gridWidth }, () => false),
  );

  layouts.forEach((item) => {
    for (let x = item.x; x < item.x + item.w; x += 1) {
      for (let y = item.y; y < item.y + item.h; y += 1) {
        if (grid[y] && grid[y][x] !== undefined) {
          grid[y][x] = true;
        }
      }
    }
  });

  for (let y = 0; y <= gridHeight - newItemHeight; y += 1) {
    for (let x = 0; x <= gridWidth - newItemWidth; x += 1) {
      let hasSpace = true;

      for (let dx = 0; dx < newItemWidth; dx += 1) {
        for (let dy = 0; dy < newItemHeight; dy += 1) {
          if (grid[y + dy][x + dx]) {
            hasSpace = false;
            break;
          }
        }
        if (!hasSpace) break;
      }

      if (hasSpace) {
        return { x, y };
      }
    }
  }

  return { x: 0, y: Infinity };
};

const getSm = ({
  layouts,
  selectedBlockId,
  currentBlock,
}: {
  layouts: Layout;
  selectedBlockId?: string | null;
  currentBlock?: { w: number; h: number };
}) => {
  const foundItem = selectedBlockId
    ? layouts.find((item) => item.id === selectedBlockId)
    : undefined;

  if (foundItem && currentBlock) {
    const beneathPositionY = foundItem.y + foundItem.h - 1;

    return {
      x: foundItem.x,
      y: beneathPositionY,
      w: currentBlock.w || 1,
      h: currentBlock.h || 1,
    };
  }

  if (foundItem) {
    const beneathPositionY = foundItem.y + foundItem.h - 1;

    return {
      x: foundItem.x,
      y: beneathPositionY,
      w: foundItem.w,
      h: foundItem.h,
    };
  }

  if (currentBlock) {
    const position = findEmptyPosition({
      layouts,
      newItemHeight: currentBlock.h || 1,
      newItemWidth: currentBlock.w || 1,
      gridWidth: 4,
      gridHeight: 1000,
    });

    return {
      x: position.x,
      y: position.y,
      w: currentBlock.w || 1,
      h: currentBlock.h || 1,
    };
  }

  return undefined;
};

const collides = (a: LayoutItem, b: LayoutItem) =>
  a.x < b.x + b.w && a.x + a.w > b.x && a.y < b.y + b.h && a.y + a.h > b.y;

const resolveDropLayout = ({
  layout,
  dropItem,
}: {
  layout: Layout;
  dropItem: LayoutItem;
}): Layout => {
  const placed: LayoutItem[] = [{ ...dropItem }];
  const next: LayoutItem[] = [{ ...dropItem }];
  const sorted = layout
    .filter((item) => item.id !== dropItem.id)
    .map((item) => ({ ...item }))
    .sort((a, b) => (a.y === b.y ? a.x - b.x : a.y - b.y));

  for (const item of sorted) {
    let candidate = { ...item };
    let needsPlacement = true;

    while (needsPlacement) {
      needsPlacement = false;
      let nextY = candidate.y;

      for (const placedItem of placed) {
        if (collides(candidate, placedItem)) {
          nextY = Math.max(nextY, placedItem.y + placedItem.h);
          needsPlacement = true;
        }
      }

      if (needsPlacement) {
        candidate = { ...candidate, y: nextY };
      }
    }

    placed.push(candidate);
    next.push(candidate);
  }

  return next;
};

const getPointerCoordinates = (event?: Event | null) => {
  if (!event) return null;
  if ("touches" in event) {
    const touchEvent = event as TouchEvent;
    const touch = touchEvent.touches[0] ?? touchEvent.changedTouches[0];
    if (touch) {
      return { x: touch.clientX, y: touch.clientY };
    }
  }
  if ("clientX" in event && "clientY" in event) {
    const mouseEvent = event as MouseEvent;
    return { x: mouseEvent.clientX, y: mouseEvent.clientY };
  }
  return null;
};

type PaletteDraggableProps = {
  item: PaletteItem;
  isActive: boolean;
  onClick?: (item: PaletteItem) => void;
};

const PaletteDraggable = ({
  item,
  isActive,
  onClick,
}: PaletteDraggableProps) => {
  const { attributes, listeners, setNodeRef, isDragging } = useDraggable({
    id: item.id,
    data: {
      palette: item,
    },
  });

  return (
    <button
      ref={setNodeRef}
      type="button"
      {...listeners}
      {...attributes}
      onClick={() => {
        if (isDragging) return;
        onClick?.(item);
      }}
      style={{
        border: `1px solid ${isActive || isDragging ? "#0f172a" : "#e5e7eb"}`,
        borderRadius: 8,
        padding: "8px 12px",
        textAlign: "left",
        fontSize: 12,
        cursor: "grab",
        background: "#fff",
        opacity: isDragging ? 0.4 : 1,
      }}
    >
      <div style={{ fontWeight: 600 }}>{item.title}</div>
    </button>
  );
};

export function KitchenSinkExample() {
  const [items, setItems] = useState<GridItem[]>(initialItems);
  const [selectedId, setSelectedId] = useState<string | null>(null);
  const [hoveredId, setHoveredId] = useState<string | null>(null);
  const [isEditing, setIsEditing] = useState(false);
  const [activePaletteId, setActivePaletteId] = useState<string | null>(null);
  const gridApiRef = useRef<DndGridHandle | null>(null);
  const dragItemRef = useRef<PaletteItem | null>(null);
  const dragPointerOffsetRef = useRef<{ x: number; y: number } | null>(null);
  const isOverGridRef = useRef(false);
  const gridRef = useRef<HTMLDivElement | null>(null);
  const nextIdRef = useRef(1);

  const sensors = useSensors(
    useSensor(MouseSensor, { activationConstraint: { distance: 10 } }),
    useSensor(TouchSensor, {
      activationConstraint: { delay: 250, tolerance: 10 },
    }),
    useSensor(KeyboardSensor),
  );

  const layout = useMemo<Layout>(
    () =>
      items.map(({ id, x, y, w, h }) => ({
        id,
        x,
        y,
        w,
        h,
      })),
    [items],
  );

  const activePaletteItem = useMemo(
    () => paletteItems.find((item) => item.id === activePaletteId) ?? null,
    [activePaletteId],
  );

  const selectItem = useCallback((id: string | null) => {
    setSelectedId(id);
    setHoveredId(id);
    setIsEditing(Boolean(id));
  }, []);

  const resetDndState = useCallback((clearDragItem = true) => {
    setActivePaletteId(null);
    if (clearDragItem) {
      dragItemRef.current = null;
    }
    dragPointerOffsetRef.current = null;
    isOverGridRef.current = false;
  }, []);

  const handleLayoutChange = (nextLayout: Layout) => {
    setItems((prev) =>
      prev.map((item) => {
        const next = nextLayout.find((layoutItem) => layoutItem.id === item.id);
        return next ? { ...item, ...next } : item;
      }),
    );
  };

  const handleDelete = (id: string) => {
    setItems((prev) => prev.filter((item) => item.id !== id));
    if (selectedId === id) {
      selectItem(null);
    }
  };

  const handleDuplicate = (id: string) => {
    const source = items.find((item) => item.id === id);
    if (!source) return;
    const sm = getSm({ layouts: layout, selectedBlockId: id });
    if (!sm) return;
    const nextId = `k${nextIdRef.current}`;
    nextIdRef.current += 1;
    setItems((prev) => [
      ...prev,
      {
        ...source,
        id: nextId,
        x: sm.x,
        y: sm.y,
        w: sm.w,
        h: sm.h,
      },
    ]);
    selectItem(nextId);
  };

  const handlePaletteClick = (item: PaletteItem) => {
    const sm = getSm({
      layouts: layout,
      currentBlock: { w: item.w, h: item.h },
    });
    if (!sm) return;
    const nextId = `k${nextIdRef.current}`;
    nextIdRef.current += 1;
    setItems((prev) => [
      ...prev,
      {
        id: nextId,
        title: item.title,
        w: sm.w,
        h: sm.h,
        x: sm.x,
        y: sm.y,
      },
    ]);
    selectItem(nextId);
  };

  const handleDropDragOver = () => {
    const active = dragItemRef.current;
    return active ? { w: active.w, h: active.h } : undefined;
  };

  const handleDrop = (_layout: Layout, item?: LayoutItem | null) => {
    const active = dragItemRef.current;
    if (!active || !item) return;
    const nextId = `k${nextIdRef.current}`;
    nextIdRef.current += 1;
    setItems((prev) => {
      const prevLayout = prev.map(({ id, x, y, w, h }) => ({
        id,
        x,
        y,
        w,
        h,
      }));
      const dropItem: LayoutItem = {
        id: nextId,
        x: item.x,
        y: item.y,
        w: item.w,
        h: item.h,
      };
      const nextLayout = resolveDropLayout({
        layout: prevLayout,
        dropItem,
      });
      const layoutById = new Map(nextLayout.map((entry) => [entry.id, entry]));
      const nextItems = prev.map((entry) => {
        const next = layoutById.get(entry.id);
        return next ? { ...entry, ...next } : entry;
      });
      const dropLayout = layoutById.get(nextId);
      if (dropLayout) {
        nextItems.push({
          id: nextId,
          title: active.title,
          w: dropLayout.w,
          h: dropLayout.h,
          x: dropLayout.x,
          y: dropLayout.y,
        });
      }
      return nextItems;
    });
    dragItemRef.current = null;
    setActivePaletteId(null);
    selectItem(nextId);
  };

  const handleDndDragStart = useCallback((event: DragStartEvent) => {
    const active = event.active.data.current?.palette as
      | PaletteItem
      | undefined;
    if (!active) return;
    dragItemRef.current = active;
    setActivePaletteId(active.id);
    const initial = event.active.rect.current.initial;
    const point = getPointerCoordinates(event.activatorEvent ?? null);
    if (initial && point) {
      dragPointerOffsetRef.current = {
        x: point.x - initial.left,
        y: point.y - initial.top,
      };
    } else {
      dragPointerOffsetRef.current = null;
    }
  }, []);

  const handleDndDragMove = useCallback((event: DragMoveEvent) => {
    const translated = event.active.rect.current.translated;
    if (!translated) return;

    const gridRect = gridRef.current?.getBoundingClientRect();
    if (!gridRect) {
      isOverGridRef.current = false;
      gridApiRef.current?.handleDndRect();
      return;
    }

    const offset = dragPointerOffsetRef.current;
    const pointerX = offset
      ? translated.left + offset.x
      : translated.left + translated.width / 2;
    const pointerY = offset
      ? translated.top + offset.y
      : translated.top + translated.height / 2;
    const isOverGrid =
      pointerX >= gridRect.left &&
      pointerX <= gridRect.right &&
      pointerY >= gridRect.top &&
      pointerY <= gridRect.bottom;

    isOverGridRef.current = isOverGrid;

    if (!isOverGrid) {
      gridApiRef.current?.handleDndRect();
      return;
    }

    gridApiRef.current?.handleDndRect(
      event.activatorEvent ?? new Event("dragover"),
      {
        top: pointerY,
        right: pointerX,
        bottom: pointerY,
        left: pointerX,
        width: 0,
        height: 0,
      },
    );
  }, []);

  const handleDndDragEnd = useCallback(
    (event: DragEndEvent) => {
      const shouldDrop = isOverGridRef.current;
      resetDndState(!shouldDrop);

      if (shouldDrop) {
        gridApiRef.current?.handleDndRect(
          event.activatorEvent ?? new Event("drop"),
        );
        return;
      }

      gridApiRef.current?.handleDndRect();
    },
    [resetDndState],
  );

  const handleDndDragCancel = useCallback(() => {
    resetDndState();
    gridApiRef.current?.handleDndRect();
  }, [resetDndState]);

  const selectedItem = items.find((item) => item.id === selectedId) ?? null;
  const isAddPanel = !isEditing;
  const isEditPanel = isEditing;

  return (
    <DndContext
      sensors={sensors}
      onDragStart={handleDndDragStart}
      onDragMove={handleDndDragMove}
      onDragEnd={handleDndDragEnd}
      onDragCancel={handleDndDragCancel}
    >
      <div
        style={{
          display: "grid",
          gap: 16,
          gridTemplateColumns: "minmax(0, 1fr) 240px",
        }}
      >
        <div ref={gridRef}>
          <DndGrid
            ref={gridApiRef}
            layout={layout}
            cols={4}
            rowHeight={40}
            resizeHandles={["ne", "nw", "se", "sw"]}
            onDrop={handleDrop}
            onDropDragOver={handleDropDragOver}
            onLayoutChange={handleLayoutChange}
            dragCancel=".kitchen-sink-action"
          >
            {items.map((item) => {
              const isSelected = selectedId === item.id;
              const isHovered = hoveredId === item.id;

              return (
                <div
                  key={item.id}
                  style={{
                    height: "100%",
                    position: "relative",
                    zIndex: isHovered ? 120 : "auto",
                  }}
                >
                  <button
                    type="button"
                    onMouseEnter={() => setHoveredId(item.id)}
                    onFocus={() => setHoveredId(item.id)}
                    onMouseDown={() => selectItem(item.id)}
                    onClick={() => selectItem(item.id)}
                    style={{
                      appearance: "none",
                      width: "100%",
                      height: "100%",
                      textAlign: "left",
                      border: isSelected
                        ? "2px solid #0f9d78"
                        : "1px solid #e5e7eb",
                      borderRadius: 8,
                      padding: 10,
                      fontSize: 12,
                      background: "#fff",
                      boxShadow: isHovered
                        ? "0 6px 18px rgba(15, 23, 42, 0.08)"
                        : "none",
                      cursor: "grab",
                    }}
                  >
                    <div style={{ fontWeight: 600 }}>{item.title}</div>
                  </button>
                  {isHovered && (
                    <div
                      className="kitchen-sink-action"
                      style={{
                        position: "absolute",
                        bottom: -34,
                        left: "50%",
                        transform: "translateX(-50%)",
                        display: "flex",
                        gap: 6,
                        border: "1px solid #e5e7eb",
                        borderRadius: 6,
                        padding: "4px 8px",
                        background: "#fff",
                        fontSize: 10,
                        zIndex: 130,
                      }}
                    >
                      <button type="button" onClick={() => selectItem(item.id)}>
                        Edit
                      </button>
                      <button
                        type="button"
                        onClick={() => handleDuplicate(item.id)}
                      >
                        Duplicate
                      </button>
                      <button
                        type="button"
                        onClick={() => handleDelete(item.id)}
                      >
                        Delete
                      </button>
                    </div>
                  )}
                </div>
              );
            })}
          </DndGrid>
        </div>

        <div
          style={{
            border: "1px solid #e5e7eb",
            borderRadius: 8,
            padding: 12,
            fontSize: 12,
          }}
        >
          <div
            style={{
              display: "flex",
              justifyContent: "space-between",
              gap: 8,
              marginBottom: 8,
              alignItems: "center",
            }}
          >
            <div style={{ display: "flex", gap: 8, alignItems: "center" }}>
              {isEditPanel && (
                <button
                  type="button"
                  onClick={() => setIsEditing(false)}
                  style={{
                    borderRadius: 999,
                    padding: "4px 10px",
                    fontSize: 10,
                    border: "1px solid #e5e7eb",
                    background: "#fff",
                  }}
                >
                  Back
                </button>
              )}
              <div style={{ fontWeight: 600 }}>
                {isEditPanel ? "Edit block" : "Add block"}
              </div>
            </div>
          </div>

          {isAddPanel ? (
            <div style={{ display: "grid", gap: 8 }}>
              {paletteItems.map((item) => (
                <PaletteDraggable
                  key={item.id}
                  item={item}
                  isActive={activePaletteId === item.id}
                  onClick={handlePaletteClick}
                />
              ))}
            </div>
          ) : (
            selectedItem && (
              <label style={{ display: "grid", gap: 4 }}>
                <div style={{ fontSize: 10, color: "#6b7280" }}>Title</div>
                <input
                  value={selectedItem.title}
                  onChange={(event) =>
                    setItems((prev) =>
                      prev.map((item) =>
                        item.id === selectedItem.id
                          ? { ...item, title: event.target.value }
                          : item,
                      ),
                    )
                  }
                  style={{
                    height: 40,
                    width: "100%",
                    borderRadius: 16,
                    border: "1px solid #e5e7eb",
                    background: "#fff",
                    padding: "0 12px",
                    fontSize: 14,
                    boxShadow: "0 1px 2px rgba(15, 23, 42, 0.08)",
                  }}
                />
              </label>
            )
          )}
        </div>
      </div>

      <DragOverlay>
        {activePaletteItem ? (
          <div
            style={{
              border: "1px solid #0f172a",
              borderRadius: 8,
              padding: "8px 12px",
              textAlign: "left",
              fontSize: 12,
              cursor: "grabbing",
              background: "#fff",
              width: 200,
              boxShadow: "0 8px 24px rgba(15, 23, 42, 0.15)",
            }}
          >
            <div style={{ fontWeight: 600 }}>{activePaletteItem.title}</div>
          </div>
        ) : null}
      </DragOverlay>
    </DndContext>
  );
}
```

## Usage

```tsx
import { KitchenSinkExample } from "@/components/dnd-grid-kitchen-sink-example";

export default function Page() {
  return <KitchenSinkExample />;
}
```

# Local storage (https://dnd-grid.blode.md/examples/localstorage)

<div className="not-prose my-6 rounded-lg border border-zinc-200/70 bg-white/70 shadow-sm dark:border-white/10 dark:bg-white/5">
  <iframe
    title="Local storage preview"
    src="https://dnd-grid.com/examples/localstorage-example?embed=1"
    className="h-[640px] w-full"
    loading="lazy"
  />
</div>

[View source on GitHub](https://github.com/mblode/dnd-grid/blob/main/apps/web/examples/dnd-grid-localstorage-example.tsx)

## Installation

### CLI

```bash
npx shadcn@latest add https://dnd-grid.com/r/localstorage-example.json
```
### Manual

```bash
npm install @dnd-grid/react
```

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

```tsx title="components/dnd-grid-localstorage-example.tsx"
"use client";

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

const STORAGE_KEY = "dnd-grid-layout";

const defaultLayout: Layout = [0, 1, 2, 3, 4, 5].map((i) => ({
  id: i.toString(),
  x: (i * 2) % 12,
  y: Math.floor(i / 6) * 2,
  w: 2,
  h: 2,
}));

export function LocalStorageExample() {
  const [layout, setLayout] = useState<Layout>(defaultLayout);

  useEffect(() => {
    const saved = localStorage.getItem(STORAGE_KEY);
    if (!saved) return;
    try {
      setLayout(JSON.parse(saved));
    } catch {
      setLayout(defaultLayout);
    }
  }, []);

  const handleLayoutChange = (newLayout: Layout) => {
    setLayout(newLayout);
    localStorage.setItem(STORAGE_KEY, JSON.stringify(newLayout));
  };

  const resetLayout = () => {
    setLayout(defaultLayout);
    localStorage.removeItem(STORAGE_KEY);
  };

  return (
    <div>
      <button type="button" onClick={resetLayout}>
        Reset Layout
      </button>

      <DndGrid
        layout={layout}
        cols={12}
        rowHeight={50}
        onLayoutChange={handleLayoutChange}
      >
        {layout.map((item) => (
          <div key={item.id} className="grid-item">
            {item.id}
          </div>
        ))}
      </DndGrid>
    </div>
  );
}
```

## Usage

```tsx
import { LocalStorageExample } from "@/components/dnd-grid-localstorage-example";

export default function Page() {
  return <LocalStorageExample />;
}
```

# Resizable handles (https://dnd-grid.blode.md/examples/resizable-handles)

<div className="not-prose my-6 rounded-lg border border-zinc-200/70 bg-white/70 shadow-sm dark:border-white/10 dark:bg-white/5">
  <iframe
    title="Resizable handles preview"
    src="https://dnd-grid.com/examples/resizable-handles-example?embed=1"
    className="h-[640px] w-full"
    loading="lazy"
  />
</div>

[View source on GitHub](https://github.com/mblode/dnd-grid/blob/main/apps/web/examples/dnd-grid-resizable-handles-example.tsx)

## Installation

### CLI

```bash
npx shadcn@latest add https://dnd-grid.com/r/resizable-handles-example.json
```
### Manual

```bash
npm install @dnd-grid/react
```

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

```tsx title="components/dnd-grid-resizable-handles-example.tsx"
"use client";

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

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

export function ResizableHandlesExample() {
  const [layout, setLayout] = useState<Layout>(initialLayout);

  return (
    <DndGrid
      layout={layout}
      cols={12}
      rowHeight={50}
      resizeHandles={["n", "e", "s", "w", "ne", "nw", "se", "sw"]}
      onLayoutChange={setLayout}
    >
      {layout.map((item) => (
        <div key={item.id} className="grid-item">
          {item.id}
        </div>
      ))}
    </DndGrid>
  );
}
```

## Usage

```tsx
import { ResizableHandlesExample } from "@/components/dnd-grid-resizable-handles-example";

export default function Page() {
  return <ResizableHandlesExample />;
}
```
---

Content truncated to keep this response under crawler size limits.
Use https://dnd-grid.blode.md/llms.txt for the full page index and fetch individual .md pages for uncapped content.