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 { setRef, style, group } = useGridContainer(() => ({
layout: props.layout,
width: props.width,
onLayoutChange: props.onLayoutChange,
dragConfig: { threshold: 4 },
}));dragConfig options
| Option | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Grid-level on/off for dragging. |
handle | string | — | CSS selector for a drag handle inside each item — only pointer-downs within it start a drag. Mainly for <GridLayout>; headless tiles should prefer setHandleRef instead. |
cancel | string | — | CSS selector for regions that should never start a drag (e.g. buttons, inputs). |
threshold | number | 3 | Pixels the pointer must travel before a drag begins, so clicks aren’t drags. Mouse and pen only — see Touch. |
bounded | boolean | false | Keep the dragged item within the grid container bounds. |
snapToGrid | boolean | false | Snap the dragged tile itself to cells while dragging (see below). |
touchHold | number | 250 | Milliseconds 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 — setHandleRef. useGridItem returns setHandleRef, a function ref. Bind it to the
grip element; only a pointer-down there starts a drag.
<!-- Tile.vue -->
<script setup>
import { useGridItem } from "@snapgridjs/vue";
const props = defineProps({ id: String, group: String });
const { setRef, setHandleRef, style } = useGridItem({ id: props.id, group: props.group });
const onEdit = () => {
/* … */
};
</script>
<template>
<div :ref="setRef" :style="style" class="tile">
<!-- drag starts here -->
<span :ref="setHandleRef" class="grip">⠿</span>
<button @click="onEdit">still clickable</button>
</div>
</template>Turnkey — dragConfig.handle. <GridLayout>’s item slot is plain markup with no function ref to
bind, 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 { setRef, style, group } = useGridContainer(() => ({ dragConfig: { handle: ".grip" }, /* … */ }));Use one or the other — setHandleRef 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).
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.
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: falseon aLayoutItemdisables dragging for that item only.static: trueanchors an item — others flow around it, and by default it can’t be dragged or resized (opt back in per item withisDraggable/isResizable: truefor a “pinned” tile). See Static items.- The grid-level
isDraggableoption overrides everything when set tofalse.
Lifecycle
onDragStart, onDrag, and onDragStop fire with the react-grid-layout-compatible signature
(layout, oldItem, newItem, placeholder, event, node). See Events & lifecycle.