selection-tools

Framework-agnostic image selection tools — rectangles, ellipses, lasso (free select), color select, magic wand, and bitmap masks.

Features

• Draw rect/ellipse selections by dragging
• Lasso (free select) tool: click to place polygonal nodes, drag to draw freehand curves, mix both freely
• Color select and magic wand tools for pixel-based selection
• Resize and move committed selections via handles
• Bitmap mask mode with Shift (add) / Ctrl (subtract) modifiers
• Shared selection state across all tools (GIMP-like behavior)
• Animated marching-ants canvas overlay
• Automatic cursor management
• Copy selection to clipboard (Ctrl+C / Cmd+C)
• Works with any framework — React, Vue, Svelte, vanilla JS, etc.

Install

npm install selection-tools

Quick start — mount()

Wrap an <img> in a container div, then call mount():

<div id="container">
  <img src="photo.jpg" />
</div>

import { SelectionToolkit } from "selection-tools";

const toolkit = new SelectionToolkit({
  onChange(state) {
    console.log(state.activeTool, state.mask);
  },
});

const cleanup = toolkit.mount(document.getElementById("container"));

toolkit.setTool("magic-wand");
toolkit.setTolerance(20);
toolkit.clearSelection();

// Tear down when done
cleanup();

mount() handles everything: finds the <img>, creates and positions the overlay canvas, applies required styles, binds all events, and auto-updates the cursor.

SelectionToolkitOptions

Option	Type	Default	Description
onChange	(state: ToolkitState) => void	required	Called after every state mutation
tool	ToolType	"rect"	Initial tool
tolerance	number	10	Color tolerance for pixel tools (0–100)
zoom	number	1	Display zoom factor
getBounds	() => { w, h } | null	auto	Drawable area dimensions; defaults to image client size

ToolkitState

Field	Type	Description
activeTool	ToolType	Current tool
cursorStyle	string	CSS cursor value (auto-applied by mount())
mask	SelectionMask | null	The shared bitmap mask
maskOutlines	string[]	SVG path d strings for the mask boundary
maskVersion	number	Increments on every mask change
selection	SelRect | null	Active rect/ellipse in display coordinates
dragPhase	DragPhase	"idle" / "drawing" / "committed"
handleLayout	HandleLayout | null	Pre-computed resize handle rects
lassoNodes	{ x, y }[]	Lasso polygon vertices
lassoPhase	string	"idle" / "placing" / "committed"

SelectionToolkit methods

Method	Description
mount(container)	All-in-one setup. Returns cleanup function.
setTool(tool)	Switch to "rect" / "ellipse" / "freehand" / "color-select" / "magic-wand"
setTolerance(n)	Set pixel tool tolerance (0–100)
clearSelection()	Clear the entire selection and mask
getState()	Get the current ToolkitState snapshot
getSelectedPixels()	Extract selected pixels as cropped RGBA data
copySelection()	Copy selection to clipboard as PNG
configure(opts)	Update getBounds, zoom, or tolerance
setMask(mask)	Programmatically set the selection mask
computeOutlines()	Recompute mask outlines (returns true if changed)
transformSelection(fn)	Transform the active rect/ellipse selection

Advanced setup

For cases where mount() doesn't fit (e.g. you manage the canvas yourself), use the individual methods:

const toolkit = new SelectionToolkit({
  onChange(state) {
    /* ... */
  },
});

const cleanups = [
  toolkit.attachImage(imgElement),
  toolkit.bindEvents(containerElement),
  toolkit.attachCanvas(canvasElement),
];

// Tear down
cleanups.forEach((fn) => fn());
toolkit.destroy();

Tools

Rectangle & Ellipse

Click and drag to draw a selection. After committing, resize via handles or move by dragging inside.

Lasso (free select)

Action	Effect
Click	Place a polygonal anchor node
Click + drag	Draw a freehand curve (auto-simplified on release)
Click on start node	Close the polygon and commit to mask
Double-click	Close with a straight line back to start and commit
Enter	Commit the current path to mask
Backspace	Undo the last action (node or freehand stroke)
Escape	Cancel and clear the path
Drag an anchor node	Reposition the node; adjacent freehand curves deform

Color Select

Click on a pixel to select all pixels of that color across the entire image.

Magic Wand

Click on a pixel to flood-fill select contiguous pixels within the tolerance.

Modifiers

Hold Shift while clicking/drawing to add to the selection, or Ctrl to subtract. Works across all tools.

Coordinate systems

The toolkit uses two coordinate systems:

• Display coordinates — scaled by the current zoom factor. UI events, SelRect, and handle positions all use display coordinates.
• Native coordinates — 1:1 with image pixels. The bitmap mask and pixel tools (colorSelect, magicWand) operate in native coordinates.

Use toNativeRect(rect, zoom) to convert a display-coordinate rectangle to native coordinates before applying it to a mask.

Bitmap mask utilities

import {
  createMask,
  maskApplyRect,
  maskApplyEllipse,
  maskApplyPolygon,
  toNativeRect,
  extractMaskedPixels,
  extractOutlines,
} from "selection-tools";

const mask = createMask(imageWidth, imageHeight);

// Convert display rect to native coords before masking
const nativeRect = toNativeRect(displaySelection, zoom);
maskApplyRect(mask, nativeRect, "replace");

const pixels = extractMaskedPixels(mask, ctx.getImageData(0, 0, w, h).data);

const paths = extractOutlines(mask);

Mask mode	Effect
"replace"	Clears the mask, then sets the new shape
"add"	Union — adds the shape to the existing mask
"subtract"	Difference — removes the shape from the existing mask

Low-level controllers

For maximum control, use SelectionController and LassoController directly:

import { SelectionController, LassoController } from "selection-tools";

const ctrl = new SelectionController({
  getBounds: () => ({ w: canvas.width, h: canvas.height }),
  onChange: (state) => render(state),
  scheduleFrame: null,
});

canvas.addEventListener("mousedown", (e) => {
  ctrl.handlePointerDown({
    x: e.offsetX,
    y: e.offsetY,
    button: e.button,
    shiftKey: e.shiftKey,
    ctrlKey: e.ctrlKey,
  });
});
window.addEventListener("mousemove", (e) => {
  ctrl.handlePointerMove({
    x: e.offsetX,
    y: e.offsetY,
    button: e.button,
    shiftKey: e.shiftKey,
    ctrlKey: e.ctrlKey,
  });
});
window.addEventListener("mouseup", () => ctrl.handlePointerUp());

Examples

Working examples are in examples/. Each is a self-contained Vite project:

cd examples/<framework>
npm install
npm run dev

Framework	Directory	Description
React	examples/react/	All five tools with SelectionToolkit
Vanilla JS	examples/vanilla/	All five tools, no framework
Vue 3	examples/vue/	Composition API with <script setup>
Svelte 5	examples/svelte/	Runes ($state)

All examples use SelectionToolkit.mount() for setup.

License

MIT