react-shape-editor

React Shape Editor

Basic yet flexible shape editor component

Other projects using react-shape-editor:

• Bounding Box Labeler by @fritz-c (source)
• (Submit a PR to add yours here!)

Installation

npm i react-shape-editor

Usage / CodeSandbox Examples

• Basic Example with Drawing
• Selection or Drawing Toggle
• Selection and Drawing Hybrid
• Bounding Boxes on Video
• Performance Test

Components

ShapeEditor

The wrapper for the entire editor component. Contains the <svg> element.

Prop	Type	Default	Description
children (required)	renderable elements		Will include components such as wrapShape-wrapped shapes, other library components (SelectionLayer/ImageLayer/DrawLayer) or arbitrary SVG elements
vectorHeight (required)	number		Height of the <svg> element viewBox (minus padding), in user units.
vectorWidth (required)	number		Width of the <svg> element viewBox (minus padding), in user units.
padding	number|object	0	Padding inside the <svg>, in px. Useful for displaying SVG content that would normally get clipped off by the edge of the SVG element. Can also help when providing contextual information (e.g., the surrounding parts of an image) while keeping the 0,0 coordinates on the part of the image you are focused on, avoiding having to convert the coordinates back-and-forth. Can be set via a number to apply to all edges, or as an object in the form: { top: number, right: number, bottom: number, left: number } to apply per-side.
scale	number	1	Scale factor of the svg contents. For example, given a vectorWidth of 100 and a scale of 0.5, the rendered DOM element will be 50 px wide.
focusOnAdd	bool	true	If true, focus on newly created elements.
focusOnDelete	bool	true	If true, focus on the next-closest element after a shape is deleted.
style	object	{}	Style to apply to the <svg> element.

---

wrapShape (Higher-Order Component)

When used to wrap an SVG element, adds resize handles and enables resize and movement functionality.

Usage

const WrappedRect = wrapShape(({ height, width /* ... "wrapShape Props Received" */ }) => (
  <rect fill="blue" height={height} width={width} />
))

// later, in render()

<WrappedRect
  shapeId={myId}
  x={12}
  y={56}
  width={20}
  /* ... "WrappedShape Props" */
/>

wrapShape Props Received

Prop	Type	Description
height	number	Height of the shape.
width	number	Width of the shape.
scale	number	Scale of the parent <svg> element, provided so you can render strokes or other components that maintain a constant size at every zoom level.
shapeId	string	Unique identifier for the shape.
x	number	x-axis offset of the shape. NOTE: You should not use this to set the position of your shape, because the <g> that wraps the shape already includes this offset.
y	number	y-axis offset of the shape. NOTE: You should not use this to set the position of your shape, because the <g> that wraps the shape already includes this offset.
disabled	bool	If true, the shape cannot be moved or resized, and shows no resize handles.
isBeingChanged	bool	If true, the shape is currently being moved or scaled.
active	bool	If true, the shape has HTML-native focus or is selected via a SelectionLayer.
nativeActive	bool	If true, the shape has HTML-native focus (keyboard events will get applied to it).
isInSelectionGroup	bool	If you assigned it via a prop on the WrappedShape, this will be available to tell whether or not the shape is in a group of two or more selected shapes (when using the SelectionLayer component). Useful for hiding the resize handles when selected in a group, or adding an outline.
extraShapeProps	object	Contains all props passed in via the extraShapeProps prop on the wrapped shape.

WrappedShape Props

Prop	Type	Default	Description
height (required)	number		Height of the shape.
shapeId (required)	string		Unique identifier for the shape, to aid in data handling.
width (required)	number		Width of the shape.
x (required)	number		x-axis offset of the shape.
y (required)	number		y-axis offset of the shape.
onChange	func	()=>{}	Listener for transformation of this shape triggered by interactions with resize handles, panning, or keyboard shortcuts. Required for user-triggered shape transformations to work. Signature: (newRect: { x: number, y: number, height: number, width: number }, WrappedShapeProps: object) => void
onDelete	func	()=>{}	Listener for the deletion of this shape via backspace or delete keys. Required for user-triggered shape deletion to work. Signature: (event: Event, WrappedShapeProps: object) => void
active	bool	false	If true, the shape is rendered as focused (particularly important when using a SelectionLayer). When not using a selection layer, this prop can be left unset, as native HTML focus will handle focus state.
constrainMove	func	non-constraining function	A callback for restricting movement during shape transformations (e.g., to lock movement to one axis, keeping the shape inside a predefined boundary or snapping it to a grid). Signature: ({ originalX: number, originalY: number, x: number, y: number, width: number, height: number }) => ({ x: number, y: number })
constrainResize	func	non-constraining function	A callback for restricting resizing during shape transformations (e.g., to lock resizing to one axis, keeping the shape inside a predefined boundary or snapping it to a grid). Signature: ({ originalMovingCorner: { x: number, y: number }, startCorner: { x: number, y: number }, movingCorner: { x: number, y: number }, lockedDimension: one of "x" or "y" }) => ({ x: number, y: number })
disabled	bool	false	If true, the shape cannot be moved or resized, and shows no resize handles.
isInSelectionGroup	bool	false	Whether or not the shape is in a group of two or more selected shapes (when using the SelectionLayer component). Prop is merely forwarded to the wrapped component to be used in customized rendering, e.g., hiding the resize handles when selected in a group, or adding an outline.
keyboardTransformMultiplier	number	1	Multiplier for keyboard-triggered transforms, such as ↑↓←→ keys to move or shift+↑↓←→ keys to resize. For example, with the default setting of 1, pressing → would move the shape 1 px to the right. With a setting of 5, it would move 5px.
onKeyDown	func	()=>{}	Listener for shape keydown event. If event.preventDefault() is called inside, it will override the default keyboard shortcut behavior. Signature: (event: Event, WrappedShapeProps: object) => void
onBlur	func	()=>{}	Listener for shape blur event. Signature: (event: Event, WrappedShapeProps: object) => void
onFocus	func	()=>{}	Listener for shape focus event. Signature: (event: Event, WrappedShapeProps: object) => void
ResizeHandleComponent	Component	DefaultResizeHandleComponent	The component to use for shape handles.
wrapperProps	object	{}	Extra props to add to the SVG <g> element wrapping the shape.
extraShapeProps	object	{}	A way to pass props down as-is to the shape component being wrapped.

---

ImageLayer

Renders an svg image element.

Prop	Type	Default	Description
src (required)	string		URL for the image to display.
onLoad	func	()=>{}	Callback for the image load. Signature: ({ naturalWidth: number, naturalHeight: number }) => void

---

DrawLayer

Creates an invisible layer of the SVG that allows users to draw shapes via mouse click-and-drag.

Prop	Type	Default	Description
onAddShape (required)	func		Callback for when a shape has finished being drawn. Use it to add the new shape to your data. Signature: (newRect: { x: number, y: number, height: number, width: number }) => void
constrainMove	func	non-constraining function	A callback for restricting the initial starting location for the drawing (e.g., to lock movement to one axis, keeping the shape inside a predefined boundary or snapping it to a grid). Signature: ({ originalX: number, originalY: number, x: number, y: number, width: number, height: number }) => ({ x: number, y: number })
constrainResize	func	non-constraining function	A callback for restricting the dragged corner when drawing a shape (e.g., to lock resizing to one axis, keeping the shape inside a predefined boundary or snapping it to a grid). Signature: ({ originalMovingCorner: { x: number, y: number }, startCorner: { x: number, y: number }, movingCorner: { x: number, y: number }, lockedDimension: one of "x" or "y" }) => ({ x: number, y: number })
DrawPreviewComponent	wrapShape(Component)	DefaultDrawPreviewComponent	The component to preview the shape while dragging. Must be wrapped with wrapShape.
onDrawStart	func	()=>{}	Called when a draw action begins. Signature: ({ startCorner: { x: number, y: number } }) => void
onDraw	func	()=>{}	Called mid-draw. Signature: ({ startCorner: { x: number, y: number }, movingCorner: { x: number, y: number } }) => void
onDrawEnd	func	()=>{}	Called when a draw action ends. canceled indicates if it ended due to being canceled via the Escape key. Signature: ({ startCorner: { x: number, y: number }, movingCorner: { x: number, y: number }, canceled: boolean }) => void

---

SelectionLayer

Creates an invisible layer of the SVG that allows users to select shapes via mouse click-and-drag.

Prop	Type	Default	Description
selectedShapeIds (required)	string[]		shapeIds that belong to the currently selected group. Should be populated with shapeIds passed back from onSelectionChange.
onSelectionChange	func	()=>{}	Listener for the addition or removal of shapes from the selection group (e.g., by shift+clicking extra shape or drawing new selection). Required for user-triggered selection to work. Signature: (selectedShapeIds: string[]) => void
onChange	func	()=>{}	Listener for transformation of shapes in the selection triggered by interactions with resize handles, panning, or keyboard shortcuts. Required for user-triggered shape transformations on selections to work. Signature: (newRects: { x: number, y: number, height: number, width: number }[], selectedShapesProps: object[]) => void
onDelete	func	()=>{}	Listener for the deletion of all shapes in this selection via backspace or delete keys. Required for user-triggered shape deletion to work. Signature: (event: Event, selectedShapesProps: object[]) => void
SelectionDrawComponent	wrapShape(Component)	DefaultSelectionDrawComponent	The component to preview the selection while dragging. Must be wrapped with wrapShape.
SelectionComponent	wrapShape(Component)	DefaultSelectionComponent	The component that visually wraps around the selected shapes (i.e., the selection outline). Must be wrapped with wrapShape.
minimumDistanceForSelection	number	15	Minimum height or width that the drawn selection must be in order to perform the selection.
keyboardTransformMultiplier	number	1	Multiplier for keyboard-triggered transforms, such as ↑↓←→ keys to move or shift+↑↓←→ keys to resize. For example, with the default setting of 1, pressing → would move shapes in the selection 1 px to the right. With a setting of 5, they would move 5px.
selectionComponentProps	object	{}	Extra props to pass to the SelectionComponent.
children	renderable elements	null	wrapShape-wrapped shapes that are targets for selection by this selection group. Can also include other library components (SelectionLayer/ImageLayer/DrawLayer) or arbitrary SVG elements.

Contributing

After cloning the repository and running yarn install inside, you can use the following commands to develop and build the project.

# Starts a dev server that hosts a demo page with the component.
yarn start

# Runs the library tests
yarn test

# Lints the code with eslint
yarn lint

# Lints and builds the code, placing the result in the dist directory.
# This build is necessary to reflect changes if you're
#  `npm link`-ed to this repository from another local project.
yarn build

License

MIT