RegionSelect

When to use

Use RegionSelect when an image region must be stored as coordinates: textbook image correction, document or defect annotation, OCR correction, screenshot redaction, or product hotspots.

Its output distinguishes it from ImageCropper. ImageCropper returns a finished bitmap through onCropped(blob); RegionSelect returns coordinates. Keeping the original image plus a box lets someone correct the box later and lets a server render crops consistently. Use ImageCropper when only the finished image matters and its original location does not.

Import

Props

Exported pure functions

toImagePoint(clientX, clientY, rect, w, h) maps and clamps a pointer to image pixels. normalizeBox(a, b) creates a normalized box from two points. applyAspect(anchor, point, aspect, w, h) applies an aspect ratio within image bounds. boxMinSide(box), roundBox(box, mode?), and strokeWidthFor(w) expose the same geometry used by the component for custom renderers.

Example

Usage guidelines

• The only coordinate system is original-image pixels, not container pixels or percentages. The component draws inside <svg viewBox="0 0 naturalW naturalH">, so boxes need no conversion; only pointer coordinates are mapped from the rendered rectangle to the source image.
• No boxes render until natural dimensions are known. Reusing the previous image's ratio would place them incorrectly. Pass naturalSize when it is already stored to avoid preloading and to make server rendering or tests independent of image decoding.
• Committed coordinates are integers by default, while the drag preview remains floating point. Database integer arrays, PIL/OpenCV/sharp crop APIs, and equality checks all need deterministic integer coordinates. The default round="expand" floors the top-left and ceils the bottom-right so rounding never shrinks a box below minSide. The minSide check therefore runs after rounding.
• A 1:1 or integer scale hides this defect because mapped coordinates are already integers. Test a non-divisible scale; the library regression coverage uses 756 source pixels rendered at 396 pixels.
• Pointer capture happens after drag state is established and is protected by try/catch. Synthetic PointerEvents in browser automation and unit tests can throw from setPointerCapture; this must not cancel the drag handler.
• The canvas uses touch-none so a touch drag selects a region instead of scrolling the page.
• Outline width scales as max(2, naturalW / 400), keeping boxes visible on wide scanned pages.
• Loading and failure are separate states. A missing, expired, unauthorized, or cross-origin image renders errorPlaceholder and calls onError instead of leaving someone waiting at the loading placeholder. Preloading and the SVG request share the same failure state, and changing src resets it.
• Keyboard and screen-reader users cannot draw directly on a canvas. Provide four numeric inputs bound to the same controlled value when the workflow needs a non-pointer alternative.

Related

ImageCropper · ImageViewer · Image · Annotation · Flow