# editorjs-caret-selection

> Track Caret, Selection, and easily simulate it for real-time collaboration feature

Latest version **0.0.3** (published 2024-10-25) · MIT license · 0 weekly downloads

## Install

```sh
npm install editorjs-caret-selection
pnpm add editorjs-caret-selection
yarn add editorjs-caret-selection
bun add editorjs-caret-selection
```

## Health

**Score 30/100 (F)** — status: maintenance-mode.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types; pre 1.0.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.3 |
| Published | 2024-10-25 |
| First published | 2024-10-15 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 19.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 6 |
| Author | Thomas Brillion |
| Maintainers | w99910 |
| Keywords | editorjs, caret, selection, real-time, realtime, collaboration |

## Links

- npm: https://www.npmjs.com/package/editorjs-caret-selection
- Repository: https://github.com/w99910/editorjs-caret-selection
- Homepage: https://github.com/w99910/editorjs-caret-selection#readme
- Issues: https://github.com/w99910/editorjs-caret-selection/issues
- npm.io page: https://npm.io/package/editorjs-caret-selection

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 0.0.3 (latest) — 2024-10-25
- 0.0.2 — 2024-10-21
- 0.0.1 — 2024-10-15

## README

# EditorJs Caret Selection

> TIP: In order to show approximatly correct caret position, please specify font family. 

Effortlessly track and simulate caret movements across any device. In real-time collaboration tools like Notion or Google Docs, you've likely noticed a caret indicating when another user is editing or viewing the same document.

I developed this feature because, as of this writing, the official EditorJs has not yet implemented it. Feel free to use, customize, and configure it to suit your needs. Cheers! 🥂🥂

![Demo](https://github.com/w99910/editorjs-caret-selection/raw/refs/heads/master/assets/demo.gif)

## Table Of Contents

- Installation
- Usage
- Realtime Caret Approach
- Tips
- Bugs
- License
- Support

## Installation

- ### NPM

```bash
npm i editorjs-caret-selection
```

```js
import CaretSelection from 'editorjs-caret-selection'
```

- ### Github ESM module

```js
import CaretSelection from 'https://github.com/w99910/editorjs-caret-selection/blob/master/dist/editorjs-caret-selection.js'
```

- ### Github CJS

```js
const CaretSelection = require('https://github.com/w99910/editorjs-caret-selection/blob/master/dist/editorjs-caret-selection.cjs')
```

## Usage

- ### Initialization

First initialize the class with your editorjs object, unique id, display name. 

```js
let editor = new EditorJS({
    ...
});

let caretSelection = new CaretSelection(editor, 'my-unique-id', 'Thomas');
```

You can pass HTMLElement to display parameter.

```js
let display = document.createElement('span');
display.style.background = 'red';
display.style.padding = '0px 4px';
display.style.fontSize = '10px'
display.textContent = 'Thomas';

let caretSelection = new CaretSelection(editor, 'my-unique-id', display);
```

- ### Listen Event

Once it is initialised, the `selectionChange` event is listened. Register your custom function when that event is triggered.

```js
caretSelection.onChange(function(caret){
    console.log(caret);
})
```

`caret` object contains the following attributes.
```js
type Caret = {
    id: string | number,
    display: string | HTMLElement,
    blockIndex: number,
    startOffset: number,
    endOffset: number,
    caretStyle?: object,
    selectionBoxStyle?: object,
}
```

- ### Show Caret Selection
In order to show caret, use `showSelection` method by passing `caret` object.

```js
caretSelection.showSelection(caret);
```

You can customize caret style and selection box style by modifying `caret` object.

```js
caret.caretStyle.background = 'red'
caret.selectionBoxStyle.background = 'red'

caretSelection.showSelection(caret);
```

- ### Hide Caret 

Use `hideSelection` method to hide specific caret by passing caret's `unique-id`. 

```js
caretSelection.hideSelection('my-unique-id');
```

- ### Get Current Caret and Selection

```js
let caret = caretSelection.getCurretSelection();
```

## Tips

In order to calculate approximately correct caret position, please specify font family instead of letting browser determine the font family.

## Realtime Caret Approach

<!-- Please refer to the article here for a more detailed explanation of the approach. -->
I will write an article about this.

## Bugs and Features
Please kindly submit your issue or request your feature [here](https://github.com/w99910/editorjs-caret-selection/issues).


## License
 MIT

## Support

I am in need of financial assistance, and I would deeply appreciate [any support you can offer](https://github.com/sponsors/w99910), even the smallest amount. 🙏🙏

---
_Source: https://npm.io/package/editorjs-caret-selection · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._