React Mark Image

Installation

npm install --save react-mark-image
# or
yarn add react-mark-image

Usage

import React, { useState } from 'react';
import { Annotation, IAnnotation } from 'react-mark-image';

export default function Simple() {
  const [annotations, setAnnotations] = useState<IAnnotation[]>([]);

  return (
    <Annotation
      src={IMAGE_URL}
      alt="Cats"
      annotations={annotations}
      onAnnotationsUpdate={setAnnotations}
      allowTouch
    />
  );
}

Props

Prop	Description	Default
src	Image src attribute
alt	Image alt attribute
annotations	Array of annotations
children	Any react elements that needs to be added next to marked image
className	class name that needs to be applied to the parent div
editorMode	Can be one of AnnotateWithText, AnnotateOnly, ReadOnlyWithSelection or ReadOnly. When AnnotateWithText is used, annotation will need text which is rendered when the annotation is hovered. In ReadOnly new annotations cannot be added
idFunction	Function to be used for creating ids of annotation objects
renderContent	Function that renders Content	See custom components
renderEditor	Function that renders Editor Component	See custom components
renderShape	Function that renders Shape Component	See custom components
renderOverlay	Function that renders Overlay	See custom components
selectors	Array of selectors that should be available
allowedShapes	Array of allowedShapes.
onAnnotationsUpdate	callback handler whenever annotations are updated
onAnnotationClick	onClick handler for annotation
onSelectedAnnotationUpdate	onSelectedAnnotationUpdate handler for annotation when it's selected. This callback takes two arguments i.e. annotation and the selected indicator
overlayOptions	Options for overlay.	See Overlay options
style	styles that need to the applied to the parent container
toolBarOptions	Options for toolbar.	See Toolbar options

Annotation object

An Annotation object is an object that conforms to the object shape

interface AnnotationData extends Record<string, any> {
  text?: string;
  id: string;
}

export interface IGeometry {
  type: string;
  x: number;
  y: number;
  height: number;
  width: number;
}

export interface IAnnotation {
  selection?: {
    mode: string;
    anchorX?: number | null;
    anchorY?: number | null;
  };
  geometry: IGeometry;
  data: AnnotationData;
}

Using custom components

Annotation supports renderProps for almost every internal component.

This allows you to customize everything about the the look of the annotation interface, and you can even use canvas elements for performance or more complex interaction models.

• renderShape - used for selecting annotation area (during annotation creation)
• renderEditor - appears after annotation area has been selected (during annotation creation)
• renderComponent - auxiliary component that appears when mouse is hovering over the highlight. It is passed an object that contains the annotation being hovered over. { annotation }
• renderOverlay - Component overlay for Annotation (i.e. 'Click and Drag to Annotate')

You can view the default renderProps here

Note: You cannot use :hover selectors in css for components returned by renderSelector and renderHighlight. This is due to the fact that Annotation places DOM layers on top of these components, preventing triggering of :hover

Overlay Options

Overlay options are of the format

export interface OverlayOptions {
  displayOverlay?: boolean;
  overlayText?: string;
}

Toolbar Options

Toolbar options are of the format

export interface RenderSelectedAnnotationIconsProps {
  annotation: IAnnotation;
  unSelectAnnotation: () => void;
}

export interface ToolBarOptions {
  showToolBar?: boolean;
  showDeleteOption?: boolean;
  renderToolbarIcons?: () => ReactElement | null;
  renderSelectedAnnotationIcons?: (
    props: RenderSelectedAnnotationIconsProps
  ) => ReactElement | null;
}

This is an Advanced Topic

The Annotation API allows support for custom shapes that use custom logic such as polygon or freehand selection. This is done by defining your own selection logic and passing it as a selector in the selectors property.

Selectors are objects that must have the following properties:

• TYPE - string that uniquely identifies this selector (i.e. RECTANGLE)
• intersects - method that returns true if the mouse point intersects with the annotation geometry
• area - method that calculates and returns the area of the annotation geometry
• methods - object that can contain various listener handlers (onMouseUp, onMouseDown, onMouseMove, onClick). These listener handlers are called when triggered in the annotation area. These handlers must be reducer-like methods - returning a new annotation object depending on the change of the method

You can view a defined RectangleSelector here

License

MIT

Contributing

We use TSDX to build this project.

Commands

Build the project

npm start # or yarn start

This builds to /dist and runs the project in watch mode so any edits you save inside src causes a rebuild to /dist.

Then run either Storybook or the example playground:

Storybook

Run inside another terminal:

yarn storybook

This loads the stories from ./stories.

NOTE: Stories should reference the components as if using the library, similar to the example playground. This means importing from the root project directory. This has been aliased in the tsconfig and the storybook webpack config as a helper.

Example

Then run the example inside another:

cd example
npm i # or yarn to install dependencies
npm start # or yarn start

To do a one-off build, use npm run build or yarn build.

To run tests, use npm test or yarn test.

Configuration

Code quality is set up for you with prettier, husky, and lint-staged. Adjust the respective fields in package.json accordingly.

Jest

Jest tests are set up to run with npm test or yarn test.

Bundle analysis

Calculates the real cost of your library using size-limit with npm run size and visulize it with npm run analyze.

Deploying the Example Playground

The Playground is just a simple Parcel app, you can deploy it anywhere you would normally deploy that. Here are some guidelines for manually deploying with the Netlify CLI (npm i -g netlify-cli):

cd example # if not already in the example folder
npm run build # builds to dist
netlify deploy # deploy the dist folder

Alternatively, if you already have a git repo connected, you can set up continuous deployment with Netlify:

netlify init
# build command: yarn build && cd example && yarn && yarn build
# directory to deploy: example/dist
# pick yes for netlify.toml

## Publishing to NPM

We recommend using [np](https://github.com/sindresorhus/np).