Components

The component layer — a thin shell in the react-grid-layout style over the hooks. <GridLayout> bundles the dnd-kit DragDropProvider, the container, the items, and the placeholder, so you never touch dnd-kit directly. For full control of the markup, or to compose with other dnd-kit draggables, use the hooks. See the Component layer guide for usage; this page is the prop reference.

A dragged tile floats itself, so there’s no overlay component to render at either layer. If you need a separate floating preview, dnd-kit’s DragOverlay is re-exported from @snapgridjs/react.

GridLayout

The turnkey controlled grid. Children are keyed by their layout item’s i. It supplies its own DragDropProvider; nest several (or wrap them in SnapGridGroup) and they share one.


<GridLayout
  layout={layout}
  width={width}
  onLayoutChange={setLayout}
  gridConfig={{ cols: 12, rowHeight: 60, margin: [12, 12] }}
  resizeConfig={{ handles: ["se", "e", "s"] }}
>
  {layout.map((item) => (
    <div key={item.i}>{item.i}</div>
  ))}
</GridLayout>

Props

Prop	Type	Default	Description
`layout`	`Layout`	—	Required. Controlled array of items. Never mutated.
`width`	`number`	—	Required. Container width in px (from `useContainerWidth`).
`onLayoutChange`	`(layout: Layout) => void`	—	Called with the next layout when an interaction commits.
`gridConfig`	`Partial<GridConfig>`	see GridConfig	Columns, row height, margins, padding, maxRows.
`dragConfig`	`DragConfig`	—	Drag behaviour.
`resizeConfig`	`ResizeConfig`	`{ handles: ["se"] }`	Resize behaviour.
`dropConfig`	`DropConfig`	`{ enabled: false }`	Accept external draggables.
`accept`	`(source) => boolean`	—	dnd-kit interop: also accept a foreign sortable as a drop target.
`compactor`	`Compactor`	`verticalCompactor`	Packing algorithm.
`isDraggable`	`boolean`	`true`	Grid-level drag toggle.
`isResizable`	`boolean`	`true`	Grid-level resize toggle.
`autoSize`	`boolean`	`true`	Grow the container height to fit content.
`id`	`string`	auto (`useId`)	Stable id for the droppable surface.
`onDragStart` `onDrag` `onDragStop`	`GridEventCallback`	—	Drag lifecycle.
`onResizeStart` `onResize` `onResizeStop`	`GridEventCallback`	—	Resize lifecycle.
`onDrop`	`(layout, item, event) => void`	—	Fired when an external draggable is dropped in.
`className`	`string`	—	Appended to `snapgrid`.
`style`	`CSSProperties`	—	Merged over the surface’s positioning style.

ResponsiveGridLayout

Switches columns and layout by breakpoint as width changes. See Responsive layouts.

Props

Prop	Type	Default	Description
`width`	`number`	—	Required. Container width in px.
`layouts`	`ResponsiveLayouts`	—	Required. Per-breakpoint layout map.
`onLayoutChange`	`(layout, layouts) => void`	—	Active layout and the updated map.
`onBreakpointChange`	`(breakpoint, cols) => void`	—	Fired when the active breakpoint changes.
`breakpoints`	`Breakpoints`	`DEFAULT_BREAKPOINTS`	Breakpoint → min width (px).
`cols`	`BreakpointCols`	`DEFAULT_BREAKPOINT_COLS`	Breakpoint → column count.
`rowHeight`	`number`	`150`	Row height in px.
`margin`	`[number, number]`	`[10, 10]`	Gap between items.
`containerPadding`	`[number, number] \| null`	`null`	Surface padding; falls back to `margin`.
`compactor` `dragConfig` `resizeConfig` `isDraggable` `isResizable` `autoSize` `className` `style`			As on `GridLayout`.

GridItem

A positioned tile with stable classes (snapgrid-item, data-grid-id, data-dragging) and the configured resize handles. Memoized, so re-rendering the surface doesn’t re-render every tile. Use it inside your own surface, or let GridLayout create them.

Prop	Type	Description
`id`	`string`	Required. Matches the layout item’s `i`.
`group`	`string`	Required. The owning grid’s id (from its `useGridContainer`).
`children`	`ReactNode`	Tile content.
`className`	`string`	Appended to `snapgrid-item`.
`style`	`CSSProperties`	Merged over the positioning style.

GridPlaceholder

Renders the landing-cell marker, or nothing when idle. Takes the grid’s group. Customize with className / style, or use useGridPlaceholder for full control.

Prop	Type	Description
`group`	`string`	Required. The owning grid’s id.
`className`	`string`	Appended to `snapgrid-placeholder`.
`style`	`CSSProperties`	Merged over the default look.

SnapGridGroup

Shares one dnd-kit DragDropProvider across several sibling grids so tiles can be dragged between them. Takes only children — a thin wrapper over DragDropProvider (nesting GridLayouts already shares a provider, so this is just explicit). See Cross-grid dragging.

Item ids must be unique across all grids that share a provider.