Composables

snapgrid’s primary API. Each returns Vue refs, style strings, and function refs to bind to your own elements. See Headless usage for the full picture.

Call each one once, during component setup, and keep the handle it returns. Its fields are Vue refs — destructure the handle in <script setup> so the template auto-unwraps them (Vue only auto-unwraps refs that are top-level setup bindings; handle.style read in a template stays a ref object). In plain JS, read .value.

Elements are bound with function refs — :ref="setRef", never a template-ref object — and style is a ready-made CSS string, so bind it directly with :style="style" (don’t spread it). RefTarget in the tables below is what Vue hands a function ref: Element | ComponentPublicInstance | null | undefined.

useContainerWidth

Measures a container’s width with a ResizeObserver (SSR-safe). Replaces react-grid-layout’s WidthProvider.

<script setup>
import { useContainerWidth } from "@snapgridjs/vue";
 
const { width, mounted, setRef } = useContainerWidth({ initialWidth: 1024 });
</script>
 
<template>
  <div :ref="setRef">
    <!-- pass width to the grid -->
  </div>
</template>

useGridContainer

The grid host: takes a getter of the controlled layout + config, owns the grid’s drag/resize session, registers the droppable surface, and returns a setRef + style for your container plus the grid’s group. Options are passed as a getter (() => ({ … })) so the grid tracks your live reactive state. Call it inside a component rendered under a <DragDropProvider>.

<script setup>
import { useGridContainer } from "@snapgridjs/vue";
import Tile from "./Tile.vue";
 
const props = defineProps({ layout: Array, width: Number, onLayoutChange: Function });
 
const { setRef, style, group } = useGridContainer(() => ({
  layout: props.layout,
  width: props.width,
  onLayoutChange: props.onLayoutChange,
}));
</script>
 
<template>
  <div :ref="setRef" :style="style">
    <Tile v-for="it in layout" :key="it.i" :id="it.i" :group="group" />
  </div>
</template>

Options (UseGridControllerOptions)

The controlled state plus the per-grid config. These are exactly <GridLayout>’s props minus the class / style fallthrough attributes (here you own the surface element, so you style it directly).

Returns (GridContainerResult)

useGridItem

Wires a single tile: drag activation, positioning style, and drag state. Takes an options object, mirroring dnd-kit’s useSortable: id, group (the value its useGridContainer returned), and an optional type. Both id and group are read once at setup and are expected to stay stable for the tile’s lifetime (tiles are keyed by i, and a grid’s id is stable).

<script setup>
import { useGridItem } from "@snapgridjs/vue";
 
const props = defineProps({ id: String, group: String });
 
const { setRef, style, item } = useGridItem({ id: props.id, group: props.group });
</script>
 
<template>
  <div :ref="setRef" :style="style">{{ item?.i }}</div>
</template>

useGridResizeHandle

Models a resize handle as its own draggable. Position and style it however you like; group is the grid’s id.

<script setup>
import { useGridResizeHandle } from "@snapgridjs/vue";
 
const props = defineProps({ itemId: String, group: String });
 
const { setRef, handleProps, isResizing } = useGridResizeHandle({
  id: props.itemId,
  handle: "se",
  group: props.group,
});
</script>
 
<template>
  <span :ref="setRef" v-bind="handleProps" />
</template>

handleProps is a plain object (not a ref) carrying the marker attribute that excludes the handle from item-drag activation — v-bind it onto the element. isResizing is a ComputedRef<boolean>, true while this item is actively being resized.

useGridPlaceholder

Returns a ComputedRef<GridPlaceholderInfo | null> — where the landing-cell marker should render, or null when idle. group is the grid’s id. The result is a single ref (not a handle object), so read .value in JS; the template auto-unwraps it.

<script setup>
import { useGridPlaceholder } from "@snapgridjs/vue";
 
const props = defineProps({ group: String });
 
const placeholder = useGridPlaceholder(props.group);
</script>
 
<template>
  <div v-if="placeholder" :style="placeholder.style" />
</template>

GridPlaceholderInfo is { item: LayoutItem; style: string } — the layout entry the dragged item will land on, plus a positioning inline-style string for your element.

useResponsiveLayout

The headless engine behind ResponsiveGridLayout. Resolves the active breakpoint, columns, and layout from the container width. Options are passed as a getter so it tracks your live width/layouts.

<script setup>
import { ref } from "vue";
import { useResponsiveLayout } from "@snapgridjs/vue";
 
const props = defineProps({ width: Number });
const layouts = ref({ lg: [/* … */] });
 
const { breakpoint, cols, layout, onLayoutChange } = useResponsiveLayout(() => ({
  width: props.width,
  layouts: layouts.value,
  onLayoutChange: (active, all) => (layouts.value = all),
  onBreakpointChange: (bp, activeCols) => {},
}));
</script>

Returns the active breakpoint (ComputedRef<string>), its cols (ComputedRef<number>), the resolved layout (ComputedRef<Layout>), and a plain onLayoutChange(layout) function to pass to the grid (it updates the active breakpoint’s entry).

useGridController

Creates and owns a grid’s GridController — the observable render bridge — without rendering a surface. The advanced seam underneath useGridContainer: same options getter (UseGridControllerOptions), but it returns the controller itself (a plain object, not a ref) and leaves the droppable surface, element ref, and container style to you. Most consumers want useGridContainer instead. Must be called during setup, in a child of a <DragDropProvider>.

<script setup>
import { useGridController } from "@snapgridjs/vue";
 
const props = defineProps({ layout: Array, width: Number });
 
const controller = useGridController(() => ({ layout: props.layout, width: props.width }));
</script>

resolveController

Resolves a grid’s controller by its group (= the grid’s id) from the registry, scoped to the ambient dnd-kit manager. The registry-based alternative to the provide/inject resolution that useGridItem uses internally; reach for it for advanced composition. Throws a helpful error if the group is unresolved. Must be called during setup, inside a <DragDropProvider>.

<script setup>
import { resolveController } from "@snapgridjs/vue";
 
const props = defineProps({ group: String });
 
const controller = resolveController(props.group);
</script>

No overlay composable (tiles float themselves)

There’s no useGridDragOverlay — and no overlay component either. While you drag with a pointer, dnd-kit lifts the active tile into the browser’s top layer, so the tile you already rendered floats itself above everything and crosses between grids unclipped; on drop it settles into its new cell. Nothing extra to wire. Style the floating state through the tile’s own isDragging. See The dragged tile floats itself.

If you need a separate floating element — a clone, a ghost, different markup — dnd-kit’s DragOverlay is re-exported from @snapgridjs/vue. It’s a component, not a composable, because it owns and renders its own element, so there’s nothing for a composable to return.