use-snapping-konva

A lightweight TypeScript utility for Konva.js that adds smart snapping and visual guidelines when dragging or resizing shapes on a canvas.

Features

• Snap shapes to the stage center, stage borders, and other shapes
• Snap to left edge, center, and right edge (horizontal) and top, center, and bottom edges (vertical)
• Customizable visual snap guidelines with configurable color, thickness, and dash style
• Works with any Konva stage — no framework required
• Full TypeScript support

Installation

npm install use-snapping-konva

yarn add use-snapping-konva

Peer dependency: konva >= 8.0.0 must be installed in your project.

Usage

import Konva from "konva";
import { useSnapKonva } from "use-snapping-konva";

const { handleDragging, handleDragEnd, handleResize, handleResizeEnd } = useSnapKonva({
  snapRange: 8,
  guidelineColor: "#00dc82",
  snapToStageCenter: true,
  snapToStageBorders: true,
  snapToShapes: true,
  pageSize: { width: 1920, height: 1080 },
  workspacePadding: 1500,
  onDragEnd: (e) => {
    console.log("Drag ended", e.target.position());
  },
  onResizeEnd: (e) => {
    console.log("Resize ended", e.target.position());
  },
});

// Attach to a draggable shape
shape.on("dragmove", handleDragging);
shape.on("dragend", handleDragEnd);

// Attach to a Konva.Transformer for resize snapping
transformer.on("transform", handleResize);
transformer.on("transformend", handleResizeEnd);

TypeScript

The settings type is exported for use in your own code:

import { useSnapKonva, UseSnapKonvaSettings } from "use-snapping-konva";

const mySettings: Partial<UseSnapKonvaSettings> = {
  snapRange: 10,
  guidelineColor: "red",
};

const handlers = useSnapKonva(mySettings);

API

useSnapKonva(settings?)

Returns an object with four event handlers to attach to Konva nodes.

| Handler | Konva event | Description | |---|---|---| | handleDragging | dragmove | Calculates snapping and draws guidelines while dragging | | handleDragEnd | dragend | Clears all guidelines and invokes onDragEnd callback | | handleResize | transform | Clears guidelines during a resize | | handleResizeEnd | transformend | Clears all guidelines and invokes onResizeEnd callback |

Settings

All settings are optional. Defaults are shown below.

| Option | Type | Default | Description | |---|---|---|---| | snapRange | number | 5 | Distance in pixels within which snapping activates | | guidelineColor | string | "#00dc82" | Color of the snap guideline | | guidelineDash | boolean | true | Whether the guideline is dashed | | showGuidelines | boolean | true | Whether to draw guidelines at all | | guideThickness | number | 1 | Stroke width of the guideline | | snapToStageCenter | boolean | true | Snap to the center of the page | | snapToStageBorders | boolean | true | Snap to the edges of the page | | snapToShapes | boolean | true | Snap to edges and centers of other shapes | | pageSize | { width, height } | { width: 800, height: 600 } | The logical page dimensions | | workspacePadding | number | 1500 | Padding around the page within the stage | | onDragEnd | (e: KonvaEventObject<DragEvent>) => void | undefined | Callback invoked after drag ends and guidelines are cleared | | onResizeEnd | (e: KonvaEventObject<Event>) => void | undefined | Callback invoked after resize ends and guidelines are cleared |

Repository

https://github.com/saroto/UseSnapKonva

License

MIT © Kimsinh Seang

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

This project was inspired by and adapted from the excellent use-konva-snapping by Farid.