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

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" }, /* … */ }));

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

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.