react-canvas-masker

> 🖌️ A lightweight, flexible React component and hook for drawing and extracting masks from images using canvas. Perfect for AI workflows, in-browser image editing tools, and selective manipulation.

---

🧠 What is react-canvas-masker?

react-canvas-masker is a modern and actively maintained React library that allows users to draw freeform masks over images, extract those masked regions, and integrate with AI-powered image processing workflows or any kind of canvas-based editing tool.

It’s built as an enhanced fork of react-mask-editor, rewritten with:

- ✅ Hook-based architecture
- 🔁 Undo/redo support
- 🔧 Flexible API
- 🧼 Clean and modern codebase

---

🚀 Features

- ✅ Draw 1-bit (black/white) masks over any image using a brush tool
- 🔁 Undo/redo and clear support
- 🎨 Customizable brush: size, color, opacity, blend mode
- 🔍 Zoom and pan capabilities for precise mask editing
- 🖱️ Intuitive controls: mouse wheel zoom, space+drag panning
- 📦 Use as a component, hook, or via React context
- ⚡ Imperative API via ref
- 📱 Responsive design that adapts to container size
- 🧪 Local demo/example app included

---

📆 Installation

``bash
npm install react-canvas-masker


or

`tsx
import React from 'react';
import { MaskEditor, toMask } from 'react-canvas-masker';

const MyComponent = () => {
const canvas = React.useRef(null);
return (
<>

onClick={() => {
if (canvas.current?.maskCanvas) {
console.log(toMask(canvas.current.maskCanvas));
}
}}
>
Get Mask


);
};
`

$3

You can resume editing from a previously saved mask by passing it as the initialMask prop:

`tsx
import React from 'react';
import { MaskEditor, toMask } from 'react-canvas-masker';

const MyComponent = () => {
const canvas = React.useRef(null);
const [savedMask, setSavedMask] = React.useState(null);

return (
<>
src="https://placekitten.com/256/256"
canvasRef={canvas}
initialMask={savedMask} // Load previously saved mask
onMaskChange={(mask) => {
// Auto-save mask on changes
localStorage.setItem('myMask', mask);
}}
/>
onClick={() => {
if (canvas.current?.maskCanvas) {
const mask = toMask(canvas.current.maskCanvas);
setSavedMask(mask);
localStorage.setItem('myMask', mask);
}
}}
>
Save Mask

onClick={() => {
const loadedMask = localStorage.getItem('myMask');
if (loadedMask) {
setSavedMask(loadedMask);
}
}}
>
Load Saved Mask


);
};
`


---

⚙️ Component Props

| Prop | Type | Required | Default | Description | | | | | | | | | | | | | | | |
| -------------------- | -------------------------------- | ---------- | --------- | -------------------------------------------------------------------------------------------- | -------- | --------- | ------------- | ------------ | ------------ | ------------ | ------------ | ----------- | ----- | ------------ | ------- | -------------- | --- | -------- | ---------------------------------------------------------------------------------------------------- |
| src | string | Yes | — | Source URL of the image to edit. | | | | | | | | | | | | | | | |
| cursorSize | number | No | 10 | Radius (in pixels) of the brush for editing the mask. | | | | | | | | | | | | | | | |
| onCursorSizeChange | (size: number) => void | No | — | Callback when the user changes the brush size via mouse wheel. | | | | | | | | | | | | | | | |
| maskOpacity | number | No | 0.4 | CSS opacity, decimal between 0–1. | | | | | | | | | | | | | | | |
| maskColor | string | No | #ffffff | Hex color (with or without leading '#') for the mask. | | | | | | | | | | | | | | | |
| maskBlendMode | \"normal" | "multiply" | "screen" | "overlay" | "darken" | "lighten" | "color-dodge" | "color-burn" | "hard-light" | "soft-light" | "difference" | "exclusion" | "hue" | "saturation" | "color" | "luminosity"\ | No | normal | CSS blending mode for the mask layer. |
| onDrawingChange | (isDrawing: boolean) => void | Yes | — | Called when the user starts or stops drawing. | | | | | | | | | | | | | | | |
| maxWidth | number | No | 1240 | Maximum width for loaded images. Images larger than this will be scaled down automatically. | | | | | | | | | | | | | | | |
| maxHeight | number | No | 1240 | Maximum height for loaded images. Images larger than this will be scaled down automatically. | | | | | | | | | | | | | | | |
| crossOrigin | string | No | — | Value for the crossOrigin attribute on the underlying . Useful for CORS images. | | | | | | | | | | | | | | | |
| onUndoRequest | () => void | No | — | Called when the user requests an undo action. | | | | | | | | | | | | | | | |
| onRedoRequest | () => void | No | — | Called when the user requests a redo action. | | | | | | | | | | | | | | | |
| onMaskChange | (mask: string) => void | No | — | Called with the current mask (as a dataURL) when the mask changes. Debounced while drawing. | | | | | | | | | | | | | | | |
| initialMask | string | No | — | Pre-load an existing mask as base64 data URL. Useful for resuming editing from a saved state. | | | | | | | | | | | | | | | |
| scale | number | No | 1 | Initial zoom scale for the image editor. | | | | | | | | | | | | | | | |
| minScale | number | No | 0.8 | Minimum allowed zoom scale. | | | | | | | | | | | | | | | |
| maxScale | number | No | 4 | Maximum allowed zoom scale. | | | | | | | | | | | | | | | |
| onScaleChange | (scale: number) => void | No | — | Callback when the zoom scale changes. | | | | | | | | | | | | | | | |
| enableWheelZoom | boolean | No | true | Enable/disable zooming with the mouse wheel. | | | | | | | | | | | | | | | |
| onPanChange | (x: number, y: number) => void | No | — | Callback when the pan position changes. | | | | | | | | | | | | | | | |
| constrainPan | boolean | No | true | Enable/disable constraints that keep the image in view while panning. | | | | | | | | | | | | | | | |

---

🧩 Ref API (MaskEditorCanvasRef)

The MaskEditor component exposes useful methods via ref:

| Name | Type | Description | |
| ------------- | -------------------------------- | ------------------------------------------------- | ------------------------ |
| maskCanvas | \HTMLCanvasElement | null\ | The mask canvas element. |
| undo() | () => void | Undo the last mask change. | |
| redo() | () => void | Redo the last undone mask change. | |
| clear() | () => void | Clear the mask. | |
| resetZoom() | () => void | Reset zoom to initial scale and center the image. | |
| setPan() | (x: number, y: number) => void | Set the pan position manually. | |
| zoomIn() | () => void | Zoom in by one step (0.1 scale increment). | |
| zoomOut() | () => void | Zoom out by one step (0.1 scale decrement). | |

---

🧪 Advanced Usage

$3

You can manage the full mask editing flow yourself:

`tsx
const CustomMaskEditor = () => {
const {
canvasRef,
clear,
cursorCanvasRef,
handleMouseDown,
handleMouseUp,
key,
maskBlendMode,
maskCanvasRef,
maskOpacity,
redo,
transform,
effectiveScale,
size,
undo,
containerRef,
resetZoom,
isPanning,
setPan,
} = useMaskEditor({
src: 'https://placekitten.com/256/256',
maskColor: '#00ff00',
maxWidth: 1024, // Optional: limit image width
maxHeight: 1024, // Optional: limit image height
onDrawingChange: (drawing) => console.log(drawing),
// Zoom and pan options
scale: 1, // Initial scale
minScale: 0.5, // Minimum zoom allowed
maxScale: 5, // Maximum zoom allowed
enableWheelZoom: true, // Enable mouse wheel zoom
constrainPan: true, // Keep image in view while panning
onScaleChange: (newScale) => console.log(Zoom level: ${newScale}),
onPanChange: (x, y) => console.log(Pan position: ${x}, ${y}),
});

const transformStyle = React.useMemo(() => {
return {
position: 'absolute' as const,
top: '50%',
left: '50%',
transform: translate(-50%, -50%) scale(${effectiveScale}) translate(${transform.translateX}px, ${transform.translateY}px),
transformOrigin: 'center',
transition: isPanning ? 'none' : 'transform 0.15s ease-out',
width: size.x + 'px',
height: size.y + 'px',
display: 'block',
};
}, [transform, effectiveScale, isPanning, size]);

return (
className="react-mask-editor-outer"
style={{
maxWidth: ${1024}px,
maxHeight: ${1024}px,
minHeight: '300px',
width: '100%',
height: '100%',
}}
tabIndex={0}
>