Skip to Content
New — snapgrid now ships for SolidJS: the same dnd-kit-native, headless-first grid — drag, resize, repack, and drag between grids. See it in Solid →
SolidDocumentationGuidesDragging

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 grid = useGridContainer(() => ({ layout: props.layout, width: props.width, onLayoutChange: props.onLayoutChange, 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. Mouse and pen only — see Touch.
boundedbooleanfalseKeep the dragged item within the grid container bounds.
snapToGridbooleanfalseSnap the dragged tile itself to cells while dragging (see below).
touchHoldnumber250Milliseconds a touch must be held, nearly still, before a drag arms. 0 disables the hold, so touch arms on threshold pixels like the mouse and tiles keep touch-action: none.

Touch

A touch never drags on movement — it has to be held first (touchHold, 250 ms by default), so a grid inside a scrolling page stays scrollable on mobile:

  • Swipe a tile → the page scrolls. A finger that travels before the hold elapses is a scroll, not a drag, so tiles no longer swallow every swipe that lands on them.
  • Hold a tile ~250 ms → the drag arms; from there the tile follows your finger as it always did.
  • Lift the finger during the hold → nothing happened. A tap is still a tap, so a click or a link on a tile keeps working.

threshold still governs the mouse and the pen, so desktop dragging is unchanged, and resize handles keep dnd-kit’s own touch hold.

touchHold: 0 turns the hold off: touch drags on threshold pixels like the mouse, and tiles keep touch-action: none so a swipe that starts on one drags the tile instead of scrolling the page.

A hold that ends where it started still fires a click on the tile. If the whole tile is a link or a button, guard its click handler against the drag that just ended.

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 handleRef, dnd-kit’s native drag-handle ref callback. Attach it to the grip element; only a pointer-down there starts a drag.

import { useGridItem } from "@snapgridjs/solid"; function Tile(props: { id: string; group: string }) { const tile = useGridItem({ id: props.id, group: props.group }); const onEdit = () => { /* … */ }; return ( <div ref={tile.ref} style={tile.style()} class="tile"> {/* drag starts here */} <span ref={tile.handleRef} class="grip">⠿</span> <button onClick={onEdit}>still clickable</button> </div> ); }

Turnkey — dragConfig.handle. <GridLayout>’s render-prop child is plain markup with no handle 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 grid = 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