---
English | [简体中文](https://github.com/alienzhou/web-highlighter/blob/master/README.zh_CN.md)
## Background
It's from an idea: highlight texts on the website and save the highlighted areas just like what you do in PDF.
If you have ever visited [medium.com](http://medium.com), you must know the feature of highlighting notes: users select a text segment and click the 'highlight' button. Then the text will be highlighted with a shining background color. Besides, the highlighted areas will be saved and recovered when you visit it next time. It's like the simple demo bellow.
This is a useful feature for readers. If you're a developer, you may want your website support it and attract more visits. If you're a user (like me), you may want a browser-plugin to do this.
For this reason, the repo (web-highlighter) aims to help you implement highlighting-note on any website quickly (e.g. blogs, document viewers, online books and so on). It contains the core abilities for note highlighting and persistence. And you can implement your own product by some easy-to-use APIs. It has been used for our sites in production.
## Development
This project uses Node.js `22.15.1` and publishes ES5 output with IE11 support. With [nvm](https://github.com/nvm-sh/nvm) installed, run:
```bash
nvm use
npm ci
npm test
```
## Install
```bash
npm i web-highlighter
```
## Usage
Only two lines, highlighted when texts are selected.
```JavaScript
import Highlighter from 'web-highlighter';
(new Highlighter()).run();
```
If you need persistence, four lines make it.
```JavaScript
import Highlighter from 'web-highlighter';
// 1. initialize
const highlighter = new Highlighter();
// 2. retrieve data from backend, then highlight it on the page
getRemoteData().then(s => highlighter.fromStore(s.startMeta, s.endMeta, s.text, s.id));
// 3. listen for highlight creating, then save to backend
highlighter.on(Highlighter.event.CREATE, ({sources}) => save(sources));
// 4. auto highlight
highlighter.run();
```
## Example
A more complex example
```JavaScript
import Highlighter from 'web-highlighter';
// won't highlight pre&code elements
const highlighter = new Highlighter({
exceptSelectors: ['pre', 'code']
});
// add some listeners to handle interaction, such as hover
highlighter
.on('selection:hover', ({id}) => {
// display different bg color when hover
highlighter.addClass('highlight-wrap-hover', id);
})
.on('selection:hover-out', ({id}) => {
// remove the hover effect when leaving
highlighter.removeClass('highlight-wrap-hover', id);
})
.on('selection:create', ({sources}) => {
sources = sources.map(hs => ({hs}));
// save to backend
store.save(sources);
});
// retrieve data from store, and display highlights on the website
store.getAll().forEach(
// hs is the same data saved by 'store.save(sources)'
({hs}) => highlighter.fromStore(hs.startMeta, hs.endMeta, hs.text, hs.id)
);
// auto-highlight selections
highlighter.run()
```
Besides, there is an example in this repo (in `example` folder). To play with it, you just need ——
Firstly enter the repository and run
```bash
npm i
```
Then start the example
```
npm start
```
Finally visit http://127.0.0.1:8085/
---
Another real product built with web-highlighter (for the highlighting area on the left):
## How it works
It will read the selected range by [`Selection API`](https://caniuse.com/#search=selection%20api). Then the information of the range will be converted to a serializable data structure so that it can be store in backend. When users visit your page next time, these data will be returned and deserialized in your page. The data structure is tech stack independent. So you can use on any 'static' pages made with React / Vue / Angular / jQuery and others.
### Persistence constraints
Persisted highlights record DOM paths and text offsets relative to `$root`; they are not screen coordinates. Restore highlights only after the content is fully rendered, and keep the same `$root`, document structure, text segmentation, and `wrapTag` configuration used when the highlight was created. If a framework re-renders the content or the document changes, persisted positions can no longer be guaranteed. Use the [`Serialize.Restore` hook](./docs/ADVANCE.md#serializerestore) to implement a restoration strategy for changing content.
### Cross-paragraph persistence and DOM restoration
A cross-paragraph selection creates one continuous `HighlightSource`. If your application needs one record per paragraph, split the selection into one `Range` per paragraph before creating highlights, call `fromRange()` for each range, and persist the returned `HighlightSource` objects individually. Use the [`Serialize.RecordInfo` hook](./docs/ADVANCE.md#serializerecordinfo) to store paragraph-specific identifiers in `source.extra`.
```JavaScript
highlighter.hooks.Serialize.RecordInfo.tap((start, end) => ({
startParagraphId: start.$node.parentElement.closest('p').dataset.id,
endParagraphId: end.$node.parentElement.closest('p').dataset.id,
}));
const sources = paragraphRanges.map(range => highlighter.fromRange(range));
```
`remove(id)` and `removeAll()` remove the highlight wrappers and restore the original element hierarchy and attributes, including for cross-paragraph highlights. Browser text splitting and merging means the original TextNode object identities and event listeners attached directly to TextNodes are not preserved; delegate events from a stable parent element instead.
### Dynamic content and tables
Dynamic DOM is supported after it becomes stable. For asynchronously loaded or frequently re-rendered content, initialize and restore highlights after rendering completes. The library does not support one continuous highlight across table cells, because a wrapper cannot safely span multiple `td` or `th` elements. Use the [`Render.SelectedNodes` hook](./docs/ADVANCE.md#renderselectednodes) to split those selections into supported fragments.
For more details, please read [this article (in Chinese)](https://www.alienzhou.com/2019/04/21/web-note-highlight-in-js/).
## APIs
### 1. Options
```JavaScript
const highlighter = new Highlighter([opts])
```
Create a new `highlighter` instance.
`opts` will be merged into the default options (shown bellow).
```JavaScript
{
$root: document.documentElement,
exceptSelectors: null,
wrapTag: 'span',
style: {
className: 'highlight-mengshou-wrap'
}
}
```
All options:
| name | type | description | required | default |
|---|---|---|---|---|
| $root | `Document | HTMLElement` | the container to enable highlighting | No | `document` |
| exceptSelectors | `Array
