npm package: @markerjs/markerjs-ui
Description: marker.js UI is a simple and lightweight UI for marker.js, a library for creating image annotations.
Author: Alan Mendelevich
Latest version: 1.1.0

# marker.js UI - the "3 lines of code" UI wrapper for marker.js 3

marker.js UI is a wrapper for [marker.js 3](https://markerjs.com) bringing a full-fledged editor and viewer UI to the library. It is designed to make it super easy to integrate image annotation into your projects with minimal custom code needed. marker.js UI brings back that "3 lines of code" feel to the library that some marker.js 2 users loved.

### When to use marker.js UI vs. marker.js 3

The choice is quite simple:

- Use marker.js UI if you want to add image annotation to your project with minimal effort.
- Use marker.js 3 directly if you want to build a custom UI and have full control over the look, feel, and available functionality.

## Installation

```bash
npm install @markerjs/markerjs3 @markerjs/markerjs-ui
```

Note that you need to install both `@markerjs/markerjs3` and `@markerjs/markerjs-ui` to use marker.js UI.

The library includes TypeScript type definitions out of the box.

## Usage

### Annotation Editor

`AnnotationEditor` is a web component that, as the name suggests, allows users to annotate images easily.

Here are the "3 lines of code" to start annotating an image:

```js
const editor = new AnnotationEditor();
editor.targetImage = targetImage;
containerDiv.appendChild(editor);
```

Obviously, you'd need to import the `AnnotationEditor` class from the library first:

```js
import { AnnotationEditor } from "@markerjs/markerjs-ui";
```

And the `targetImage` in the example above is the image you want to annotate. It is an `HTMLImageElement` that can either be a reference to an image on your page, or you can create a new image element in JavaScript and set its `src` property to the image you want to annotate.

```js
const targetImage = document.createElement("img");
targetImage.src = "image.jpg";
```

#### Handling Events

There are two main events fired by the `AnnotationEditor` class: `editorsave` and `editorclose`.

The `editorclose` tells you that the user clicked the close button and you can decide what it means in your context. Most likely you want to remove the editor from the page.

The `editorsave` event is fired when the user clicks the save button. There are two properties in the event that are important to you:

- `detail.state` - the annotations that were created by the user. This is a marker.js 3 `AnnotationState` object that you can save for later.
- `detail.dataUrl` (optional) - the data URL of the annotated image. This is a base64 encoded string that you can use to display the annotated image in an `img` element or save it to a file.

Here's an example of how to handle the `editorsave` event:

```js
editor.addEventListener("editorsave", (event) => {
  console.log("Editor state:", event.detail.state);
  const dataUrl = event.detail.dataUrl;

  // download the rasterized image
  if (dataUrl) {
    const link = document.createElement("a");
    link.href = dataUrl;
    link.download = "annotation.png";
    link.click();
  }
});
```

#### Editing Annotations

To edit existing annotations, you need to load the `AnnotationState` object into the editor. You can do this by calling the `restoreState` method on the editor instance:

```js
editor.restoreState(savedState); // where savedState is your AnnotationState object
```

### Annotation Viewer

`AnnotationViewer` is a web component that allows you to display an image with an annotations overlay on top of it.

Here's how you display the previously saved annotations on an image:

```js
const viewer = new AnnotationViewer();
viewer.targetImage = targetImage;
containerDiv.appendChild(viewer);
viewer.show(savedState);
```

## Docs and Tutorials

You can find marker.js UI reference and tutorials [here](https://markerjs.com/docs-v3/).

## License

marker.js UI is licensed under the [MIT License](LICENSE).

Note that marker.js 3 has its own license, which you can find [here](https://github.com/ailon/markerjs3/blob/master/LICENSE). Alternative licenses are available on [markerjs.com](https://markerjs.com/).

## Credits

In addition to [marker.js 3] and TypeScript marker.js UI is based on the following tools and libraries (and their dependencies):

- [Vite](https://vite.dev/)
- [Tailwind CSS](https://tailwindcss.com/)
- [daisyUI](https://daisyui.com/)
- [Tabler Icons](https://tabler.io/icons)

[marker.js 3]: https://markerjs.com