Skip to Content
snapgrid is a react-grid-layout v2 alternative built on dnd-kit. Drag, resize, repack, and drag between grids.
DocumentationGuidesDragging

Dragging

Items drag by default. Configure how with dragConfig, and toggle it per item with isDraggable / static on the layout item. dragConfig is an option on useGridContainer (and, identically, a prop on the <GridLayout> shell):

const { containerProps, group } = useGridContainer({
  layout,
  width,
  onLayoutChange: setLayout,
  dragConfig: { threshold: 4 },
});

dragConfig options

OptionTypeDefaultDescription
enabledbooleantrueGrid-level on/off for dragging.
handlestring—CSS selector for a drag handle inside each item — only pointer-downs within it start a drag. Mainly for <GridLayout>; headless tiles should prefer handleRef instead.
cancelstring—CSS selector for regions that should never start a drag (e.g. buttons, inputs).
thresholdnumber3Pixels the pointer must travel before a drag begins, so clicks aren’t drags.
boundedbooleanfalseKeep the dragged item within the grid container bounds.
snapToGridbooleanfalseSnap the dragged tile itself to cells while dragging (see below).

Drag handles

Restrict dragging to a grip so the rest of the tile (buttons, inputs, links) stays interactive — two ways, matching the two layers.

Headless — handleRef. useGridItem returns dnd-kit’s native handleRef. Attach it to the grip element; only a pointer-down there starts a drag.

function Tile({ id, group }) {
  const { ref, style, handleRef } = useGridItem({ id, group });
  return (
    <div ref={ref} style={style} className="tile">
      <span ref={handleRef} className="grip">⠿</span> {/* drag starts here */}
      <button onClick={…}>still clickable</button>
    </div>
  );
}

Turnkey — dragConfig.handle. <GridLayout>’s children are plain markup with no ref to attach, so it gates by CSS selector (the react-grid-layout idiom). The selector also works headless via useGridContainer, and pairs with cancel for regions that should never start a drag.

const { containerProps, group } = useGridContainer({ dragConfig: { handle: ".grip" }, /* … */ });

Use one or the other — handleRef or the selector. If you set both, a drag has to satisfy both. Keyboard pickup is unaffected by either: a focused tile is always draggable (see below).

Drag handle
only the ⠿ grip starts a drag — the button stays clickable

Resize handles are always excluded from drag activation automatically. You never need to add them to cancel.

Snap to grid

By default the dragged tile follows the pointer smoothly and only the placeholder snaps to cells (matching react-grid-layout). Set snapToGrid: true to snap the tile itself, axis-by-axis, to the column and row pitch.

Snap to grid
toggle whether the dragged tile snaps or glides

Keyboard accessibility

Tiles are keyboard-draggable out of the box. Each tile is focusable and announced as draggable (tabindex="0", role="button", aria-roledescription="draggable"), and arrow keys move it a cell at a time:

  • Tab to focus a tile.
  • Enter or Space to pick it up.
  • Arrow keys to move it one cell at a time. The layout reflows live.
  • Enter / Space to drop, or Escape to cancel and snap back.

Keyboard dragging is in-grid only (there’s no pointer to land a tile in another grid), and, like pointer dragging, a packed axis can pull the tile back (e.g. moving down under vertical compaction).

A handle restricts only pointer dragging. Keyboard users can always pick up a focused tile with Enter/Space, so dragging stays accessible regardless of where the handle is.

Per-item control

  • isDraggable: false on a LayoutItem disables dragging for that item only.
  • static: true anchors an item — others flow around it, and by default it can’t be dragged or resized (opt back in per item with isDraggable / isResizable: true for a “pinned” tile). See Static items.
  • The grid-level isDraggable option overrides everything when set to false.

Lifecycle

onDragStart, onDrag, and onDragStop fire with the react-grid-layout-compatible signature (layout, oldItem, newItem, placeholder, event, node). See Events & lifecycle.

Last updated on
Component layerResizing