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 →
SolidDocumentationGuidesHeadless usage

Headless usage

The hooks are snapgrid’s primary API. They hand you ref callbacks, positioning-style accessors, and drag state — you bring the markup, classes, and content. Reach for them when you want full control, or to compose with the dnd-kit draggables and sortables you already have (dnd-kit interop). (<GridLayout> is a thin shell over these same hooks — see Component layer when you’d rather not wire it yourself.)

Drag & resize
drag a tile · resize from the corner

The shape of a headless grid

Two pieces, both under a dnd-kit DragDropProvider that you supply:

  1. useGridContainer(() => options) — the grid host. Returns a ref callback and style for your surface, and the grid’s group.
  2. useGridItem({ id, group }) — one tile. Returns a ref callback and positioning style.

There’s no third piece for the drag preview: a dragged tile floats itself.

import { DragDropProvider, type Layout, useGridContainer, useGridItem } from "@snapgridjs/solid"; import { For } from "solid-js"; interface BoardProps { layout: Layout; width: number; onLayoutChange: (layout: Layout) => void; } function Board(props: BoardProps) { return ( <DragDropProvider> <Surface layout={props.layout} width={props.width} onLayoutChange={props.onLayoutChange} /> </DragDropProvider> ); } function Surface(props: BoardProps) { const grid = useGridContainer(() => ({ layout: props.layout, width: props.width, onLayoutChange: props.onLayoutChange, })); return ( <div ref={grid.ref} style={grid.style()}> <For each={props.layout.map((it) => it.i)}> {(id) => <Tile id={id} group={grid.group()} />} </For> </div> ); } function Tile(props: { id: string; group: string }) { const tile = useGridItem({ id: props.id, group: props.group }); return ( <div ref={tile.ref} style={tile.style()} class="tile"> {props.id} </div> ); }

useGridContainer must run inside the provider. It registers the grid on dnd-kit’s manager, and Solid resolves context from the owner chain — a component sees providers rendered above it, never one it renders itself. So the host has to be a child component rendered inside <DragDropProvider> (like Surface), not the component that renders the provider. Calling it in the same component that renders <DragDropProvider> leaves the manager out of reach, and tiles throw no grid found for group. (SnapGridGroup is dnd-kit’s provider too, so the same rule applies.)

Iterate ids, not entries. <For> keys its rows by identity, and every commit hands you a new layout array with new entry objects — so <For each={props.layout}> would tear down and remount every tile on every drop. Map to the ids (props.layout.map((it) => it.i)): strings compare by value, so each tile stays mounted across commits.

useGridContainer — the grid host

useGridContainer(() => options) creates the grid’s controller + drag monitor and returns:

FieldWhat it is
refRef callback for your surface element: <div ref={grid.ref}>.
styleAccessor for the surface’s inline style object (position: relative + width + auto-sized height). Apply it with style={grid.style()}, or merge your own properties: style={{ ...grid.style(), … }}.
groupAccessor for this grid’s id. Pass grid.group() to every tile-level hook.
isDropTargetAccessor — true while a compatible draggable is over the grid (handy for highlighting).
controllerThe grid’s controller, for advanced composition.

Every field except ref and controller is an accessor: call it to read the current value, and read it inside JSX (or a memo/effect) so Solid tracks it. Because they’re functions rather than values, destructuring is safe — const { ref, style, group } = useGridContainer(…) stays reactive.

options is the controlled state — layout, width, onLayoutChange — plus any of gridConfig, dragConfig, resizeConfig, dropConfig, compactor, isDraggable, isResizable, autoSize, id, and the lifecycle callbacks. They’re passed as a getter — useGridContainer(() => ({ … })) — so read your props and signals inside it (props.layout, layout()): the grid re-runs the getter in a computation and republishes whenever anything it read changes. Each option is documented in its feature guide.

useGridItem — a tile

useGridItem({ id, group }) wires one tile. Unlike the container, its options are plain values, not a getter: a tile’s id and group are read once at setup and are expected to be stable for its lifetime (tiles are keyed by id, and a grid’s id is stable — remount the grid, e.g. inside a keyed <Show>, if its id must change).

FieldWhat it is
refRef callback for the tile element.
handleRefOptional drag handle — bind it to a child (ref={tile.handleRef}) to restrict pointer dragging to it (see Dragging). Leave it off and the whole tile drags.
styleAccessor for the absolute-positioning style object (position: absolute + left/top/width/height); reflow is animated on the compositor. Apply it with style={tile.style()} (merge extra properties with a spread); don’t override the position.
isDraggingAccessor — true while this tile is the active drag source. Branch your styling on it.
itemAccessor for the tile’s current (possibly reflowed) layout entry.

You choose the tag, classes, and content. snapgrid only supplies position + state.

The dragged tile floats itself

There’s no overlay to render. While you drag with a pointer, dnd-kit lifts the active tile into the browser’s top layer, so it floats above everything and crosses between grids unclipped — the same element you rendered, now floating. The other tiles reflow to open the landing cell, and on drop the tile settles into place. This is dnd-kit’s default drag feedback; snapgrid only disables the drop animation so the tile lands on the cell instead of springing back to where it started.

Because the tile is the preview, you style its dragging state right where you render it — branch on isDragging():

function Tile(props: { id: string; group: string }) { const tile = useGridItem({ id: props.id, group: props.group }); return ( <div ref={tile.ref} style={tile.style()} class="tile" data-dragging={tile.isDragging() || undefined} > {props.id} </div> ); }

Keyboard drags don’t float. With the keyboard sensor the tile stays in place and steps cell-by-cell (Enter/Space to pick up and drop, arrows to move, Escape to cancel) — so the floating behaviour is purely for pointer drags.

Need a separate floating element? For a custom preview — a clone, a ghost, different markup — dnd-kit’s DragOverlay is re-exported from @snapgridjs/solid. You rarely need it, since the tile already floats itself; reach for it only when the floating preview must differ from the tile. See Styling.

Optional affordances

Headless tiles carry nothing extra — no class names, no resize handles, no placeholder, just a ref and a style. The host and tile above are already a complete, working grid; everything else is yours to render. Two affordances are common enough that snapgrid gives you a hook for each:

  1. useGridResizeHandle({ id, handle, group }) — render resize handles on a tile.
  2. useGridPlaceholder(group) — mark the cell a dragged tile will land in.

useGridResizeHandle — render your own resize handles

Why you need it: a headless tile has no resize handles. resizeConfig.handles only declares which edges are resizable; you render the handle elements. (The <GridItem> shell does this for you — this is what it does under the hood.)

useGridResizeHandle({ id, handle, group }) models a handle as its own draggable and returns:

FieldWhat it is
refRef callback for your handle element.
handlePropsSpread onto the handle ({...resize.handleProps}) — marks it so a pointer-down resizes instead of starting an item drag.
isResizingAccessor — true while this item is being resized.

You position and style the handle however you like:

import { useGridItem, useGridResizeHandle } from "@snapgridjs/solid"; function Tile(props: { id: string; group: string }) { const tile = useGridItem({ id: props.id, group: props.group }); const resize = useGridResizeHandle({ id: props.id, handle: "se", group: props.group }); return ( <div ref={tile.ref} style={tile.style()} class="tile"> {props.id} {/* a bottom-right grip; CSS places + styles `.resize-handle` */} <span ref={resize.ref} {...resize.handleProps} class="resize-handle" /> </div> ); }

Render one handle per axis you want ("n" | "e" | "s" | "w" | "ne" | "nw" | "se" | "sw"). See Resizing for the config and per-item limits.

useGridPlaceholder — the landing marker

Why you’d use it: during a drag, the placeholder shows the cell the tile will land in — the gap that reflows live as you move. It’s optional; render it for the familiar “ghost cell” affordance.

useGridPlaceholder(group) returns an accessor that yields a { item, style } object while a drag is active, or null when idle. Render it with a non-keyed <Show> and apply its style:

import { For, Show } from "solid-js"; import { useGridContainer, useGridPlaceholder } from "@snapgridjs/solid"; function Surface(props: BoardProps) { const grid = useGridContainer(() => ({ layout: props.layout, width: props.width, onLayoutChange: props.onLayoutChange, })); // The grid's id is stable for its lifetime — read it once here. const placeholder = useGridPlaceholder(grid.group()); return ( <div ref={grid.ref} style={grid.style()}> <For each={props.layout.map((it) => it.i)}> {(id) => <Tile id={id} group={grid.group()} />} </For> <Show when={placeholder()}> {(current) => <div class="placeholder" style={current().style} />} </Show> </div> ); }

A non-keyed <Show> (the default) keeps the one marker element mounted while the placeholder moves, so a CSS transition you put on it animates between cells instead of restarting.

Fine-grained updates — nothing to memoize

Solid components run once; there’s no re-render to avoid. Each useGridItem reads only its own slice of the controller through memos: on a drag-state change every tile’s slice memo re-evaluates, but the controller hands back the same snapshot when that tile’s cell didn’t change, so its position and style memos don’t notify and its DOM isn’t touched. Only the tiles whose cell actually moved update. There’s no React-style memo to reach for — the hooks already subscribe narrowly. (<GridItem> works the same way.)

Mixing the two layers

They share one engine, so nothing is all-or-nothing. Drop <GridItem id={id} group={grid.group()}> / <GridPlaceholder group={grid.group()} /> into a surface you host with useGridContainer, or use <GridLayout> for most of the app and the hooks for the one grid that needs custom markup. See Component layer.

The hooks at a glance

HookReturnsRenders
useContainerWidth(options?){ width, mounted, ref }Nothing — measures an element.
useGridContainer(() => options){ ref, style, group, isDropTarget, controller }The surface; registers the droppable + owns the grid.
useGridItem({ id, group }){ ref, handleRef, style, isDragging, item }One positioned tile.
useGridResizeHandle({ id, handle, group }){ ref, handleProps, isResizing }One resize handle.
useGridPlaceholder(group)Accessor<{ item, style } | null>The landing-cell marker (null when idle).
useResponsiveLayout(() => options){ breakpoint, cols, layout, onLayoutChange }Nothing — resolves the active breakpoint. See Responsive.

Everything a hook returns is an accessor except the ref callbacks, handleProps, controller, and useResponsiveLayout’s onLayoutChange.

Last updated on