grid

Snap movement to a grid pattern

The grid plugin snaps draggable movement to a grid pattern. Instead of smooth, continuous movement, elements jump between grid points - perfect for alignment, layout tools, or pixel-perfect positioning.

grid([20, 20]); // 20px square grid
grid([50, 25]); // 50px wide, 25px tall rectangles
grid([10, null]); // Only snap horizontally every 10px
grid([null, 15]); // Only snap vertically every 15px

Basic Usage

<script>
  import { grid } from '@neodrag/svelte';
</script>

<!-- Square 20px grid -->
<div {@attach draggable([grid([20, 20])])}>Snaps to 20px squares</div>

<!-- Rectangular grid -->
<div {@attach draggable([grid([50, 30])])}>
  Snaps to 50x30px rectangles
</div>

<!-- Horizontal-only snapping -->
<div {@attach draggable([grid([25, null])])}>
  Only snaps horizontally
</div>

<!-- Vertical-only snapping -->
<div {@attach draggable([grid([null, 20])])}>
  Only snaps vertically
</div>

Dynamic Grid Sizing

<script>
  import { grid, Compartment } from '@neodrag/svelte';

  let gridSize = $state(20);
  let enableSnap = $state(true);

  const gridComp = Compartment.of(() =>
    enableSnap ? grid([gridSize, gridSize]) : grid([null, null]),
  );
</script>

<div {@attach draggable(() => [gridComp])}>
  Grid: {enableSnap ? `${gridSize}px` : 'disabled'}
</div>

<label>
  Grid Size: {gridSize}px
  <input
    type="range"
    bind:value={gridSize}
    min="5"
    max="50"
    step="5"
  />
</label>

<label>
  <input type="checkbox" bind:checked={enableSnap} />
  Enable Grid Snap
</label>

Advanced Grid Patterns

Asymmetric Grids

<script>
  import { grid } from '@neodrag/svelte';
</script>

<!-- Wide columns, short rows -->
<div {@attach draggable([grid([100, 20])])}>100x20px grid</div>

<!-- Timeline-style: hourly columns -->
<div {@attach draggable([grid([60, null])])}>
  60px intervals (hourly)
</div>

<!-- Calendar-style: daily columns, weekly rows -->
<div {@attach draggable([grid([80, 120])])}>Daily x Weekly</div>

Responsive Grid System

<script>
  import { grid, Compartment } from '@neodrag/svelte';

  let screenWidth = $state(window.innerWidth);

  // 12-column responsive grid
  const columnWidth = $derived(screenWidth / 12);
  const responsiveGrid = Compartment.of(() =>
    grid([columnWidth, 40]),
  );

  function handleResize() {
    screenWidth = window.innerWidth;
  }
</script>

<svelte:window on:resize={handleResize} />

<div {@attach draggable(() => [responsiveGrid])}>
  Responsive 12-column grid
  <br />
  Column: {Math.round(columnWidth)}px
</div>

Real-World Examples

Pixel Art Editor

// Precise 1px grid for pixel-perfect editing
const pixelGrid = [grid([1, 1]), bounds(BoundsFrom.element(canvas))];

Card Layout System

// Cards snap to a 12-column grid system
const containerWidth = 1200;
const columnWidth = containerWidth / 12;
const cardGrid = [
  grid([columnWidth, 40]), // 12-column, 40px row height
  bounds(BoundsFrom.parent()),
];

Timeline Editor

// Timeline with 15-minute intervals
const minutesPerPixel = 0.25; // 15 minutes = 60 pixels
const timelineGrid = [
  grid([60, null]), // 15-minute intervals horizontally
  bounds(BoundsFrom.element(timelineContainer)),
];

Icon Grid Layout

// Desktop-style icon grid
const iconSize = 64;
const iconSpacing = 80;
const iconGrid = [
  grid([iconSpacing, iconSpacing]),
  bounds(BoundsFrom.viewport({ top: 100, bottom: 50 })),
];

How It Works

The grid plugin modifies movement by snapping to grid points:

1. Calculate grid position - Uses Math.ceil(value / gridSize) * gridSize to find the next grid point
2. Apply to proposed movement - Modifies ctx.proposed.x and ctx.proposed.y
3. Null values skip snapping - null means free movement on that axis
4. Runs during drag - Continuously snaps while dragging

The snapping formula ensures elements always move forward to the next grid intersection, creating predictable, aligned positioning.

API Reference

function grid(size: [number | null, number | null]): Plugin;

Parameters:

• size - Array with [x, y] grid dimensions
  • number - Grid size in pixels for that axis
  • null - No grid snapping for that axis

Usage patterns:

• grid([20, 20]) - Square 20px grid
• grid([50, 30]) - Rectangular 50x30px grid
• grid([25, null]) - Horizontal snapping only
• grid([null, 15]) - Vertical snapping only
• grid([null, null]) - No snapping (effectively disabled)

Returns: A plugin object for use with draggable.