Editable JavaScript Text Highlights – HighlightHelper.js

HighlightHelper.js is a vanilla JavaScript library for highlighting and underlining text on web pages.

It handles overlapping highlights, selections that cross paragraph boundaries, and editable ranges with drag handles.

Features

• Text highlights across inline elements and multiple paragraphs.
• Overlapping ranges and editable or read-only highlights.
• Fill and underline styles with custom color definitions.
• SVG, CSS Custom Highlight API, and HTML mark rendering modes.
• Custom drag handles for editing selected ranges.
• Start and end wrappers for labels or annotation indicators.
• Tap, hover, selection, and highlight lifecycle events.
• Programmatic loading, updates, removal, and redraws.

How To Use It

Installation

Load the core JavaScript file from a CDN.

<script src="https://cdn.jsdelivr.net/gh/samuelbradshaw/highlight-helper-js@main/highlight-helper.min.js"></script>

Or install the npm package and import its Highlighter export.

npm install @samuelbradshaw/highlight-helper-js

import { Highlighter } from '@samuelbradshaw/highlight-helper-js';

For browser modules, import the module build directly.

import { Highlighter } from 'https://cdn.jsdelivr.net/gh/samuelbradshaw/highlight-helper-js@main/highlight-helper.min.mjs';

Basic Usage

Give each annotatable paragraph a unique id. The paragraph text and its character offsets determine where a saved highlight appears. This example loads a yellow highlight over the opening sentence.

<main id="reading-area">
  <p id="intro-line">Highlight important passages in this document.</p>
  <p id="second-line">Readers can also select other text.</p>
</main>
<script src="https://cdn.jsdelivr.net/gh/samuelbradshaw/highlight-helper-js@main/highlight-helper.min.js"></script>
<script>
  const highlighter = new Highlighter('#reading-area', 'p[id]');
  const firstParagraph = document.getElementById('intro-line');
  highlighter.loadHighlights([{
    highlightId: 'note-1',
    color: 'yellow',
    style: 'fill',
    startParagraphId: 'intro-line',
    startParagraphOffset: 0,
    endParagraphId: 'intro-line',
    endParagraphOffset: firstParagraph.textContent.length,
  }]);
</script>

Create a Highlight from Selected Text

Call createOrUpdateHighlight() after your reader selects text inside the annotatable container. Place the button outside that container and prevent its mouse press from clearing the selection. This example continues from Basic Usage. crypto.randomUUID() requires a secure context.

<button type="button" id="highlight-selection">Highlight selection</button>
<script>
  const button = document.getElementById('highlight-selection');
  button.addEventListener('mousedown', (event) => event.preventDefault());
  button.addEventListener('click', () => {
    const selection = window.getSelection();
    if (!selection || selection.isCollapsed || !selection.rangeCount) return;
    const range = selection.getRangeAt(0);
    const area = document.getElementById('reading-area');
    if (!area.contains(range.startContainer) || !area.contains(range.endContainer)) return;
    highlighter.createOrUpdateHighlight({
      highlightId: crypto.randomUUID(),
      color: 'green',
      style: 'underline',
    });
  });
</script>

Activate Highlights on Tap

Attach interaction listeners to the annotatable container. A tap can intersect multiple highlights or hyperlinks. This handler activates a highlight only when it is the sole item at that point. For overlapping items, let your reader choose before calling activateHighlight() or activateHyperlink().

const container = document.getElementById('reading-area');
container.addEventListener('hh:tap', (event) => {
  const detail = event.detail;
  if (detail.isLongPress || detail.selectionType === 'Range') return;
  if (detail.targetCount === 1 && detail.highlights.length === 1) {
    highlighter.activateHighlight(detail.highlights[0].highlightId);
  }
});

Restore and Save Highlight Data

HighlightHelper.js does not persist highlights. Store the editable fields in local storage or on a backend, then load them after the original text exists. Saved offsets depend on stable paragraph IDs and text content.

For a local-storage implementation, replace the demonstration highlighter.loadHighlights([...]) call in Basic Usage with the following code after constructing highlighter.

const readingContainer = document.getElementById('reading-area');
const STORAGE_KEY = 'reading-area-highlights';
const editableFields = [
  'highlightId', 'color', 'style', 'wrapper', 'variables', 'readOnly',
  'startParagraphId', 'startParagraphOffset',
  'endParagraphId', 'endParagraphOffset',
];
let isRestoring = true;
function saveHighlights() {
  if (isRestoring) return;
  const records = highlighter.getHighlightInfo().map((highlight) =>
    Object.fromEntries(editableFields.map((key) => [key, highlight[key]]))
  );
  localStorage.setItem(STORAGE_KEY, JSON.stringify(records));
}
for (const eventName of [
  'hh:highlightcreate', 'hh:highlightupdate', 'hh:highlightremove',
]) {
  readingContainer.addEventListener(eventName, saveHighlights);
}
let saved = [];
try {
  const parsed = JSON.parse(localStorage.getItem(STORAGE_KEY) || '[]');
  if (Array.isArray(parsed)) saved = parsed;
} catch {
  // Ignore invalid stored JSON.
}
readingContainer.addEventListener('hh:highlightsload', () => {
  isRestoring = false;
}, { once: true });
highlighter.loadHighlights(saved);

Choose a Drawing Mode

highlighter.setOptions({
  drawingMode: 'mark-elements',
  enableHover: true,
  snapToWord: true,
  colorDefs: {
    purple: '#b197fc',
  },
});

Customize Highlight Styles

You can pass templates through styleDefs to customize highlight styles. css is required for each definition. This example creates a custom fill over the opening word of second-line from Basic Usage. SVG templates can use placeholders such as {line.x} and {line.width} for each text line.

highlighter.setOptions({
  colorDefs: { purple: '#b197fc' },
  styleDefs: {
    softFill: {
      css: 'background-color: color-mix(in srgb, var(--hh-color) 45%, transparent);',
      cssActive: 'background-color: var(--hh-color);',
    },
  },
});
highlighter.createOrUpdateHighlight({
  highlightId: 'purple-note',
  color: 'purple',
  style: 'softFill',
  startParagraphId: 'second-line',
  startParagraphOffset: 0,
  endParagraphId: 'second-line',
  endParagraphOffset: 7,
}, true, false);

All Configuration Options

Default Colors

Style and Wrapper Template Properties

Each entry in styleDefs accepts these properties:

Each wrapperDefs entry accepts start and end HTML templates. Both default to null when absent. Style and wrapper templates accept var(--hh-color) and the substitutions below.

Add a Start and End Label

The built-in screen-reader-label wrapper inserts text for screen readers. Give the highlight an explicit range or create it from an existing text selection. The label text comes from variables. The example uses the first paragraph from Basic Usage.

highlighter.createOrUpdateHighlight({
  highlightId: 'accessible-note',
  startParagraphId: 'intro-line',
  startParagraphOffset: 0,
  endParagraphId: 'intro-line',
  endParagraphOffset: 9,
  wrapper: 'screen-reader-label',
  variables: {
    startLabel: 'Start of an important passage',
    endLabel: 'End of the important passage',
  },
}, true, false);

Highlight Object Reference

loadHighlights() accepts an array of highlight objects. createOrUpdateHighlight() accepts an object containing only the properties to create or change. New and active highlights can use the current text selection for their range. Existing inactive highlights retain their range until new positions are provided.

Editable Properties

Computed Properties

These properties are available in highlight information returned by the library. They should not be edited as input fields.

API Methods

Custom Events

hh:tap details include targetCount, highlights, wrappers, hyperlinks, isLongPress, and selectionType. The hh:highlightsload event reports addedCount, removedCount, updatedCount, totalCount, and loadTimeMs.

container.addEventListener('hh:selectionchange', (event) => {
  console.log(highlighter.getSelectionState());
  console.log(event.detail);
});

CSS Styling Hooks and Element Attributes

Structural Attributes

Identification and State Attributes

Other Styling and Access Hooks

• .sr-only class: Provides screen-reader-only label text in wrappers.
• --hh-color CSS custom property: Contains the current highlight color for style and drag-handle templates.
• highlighter container property: Exposes the associated Highlighter instance in JavaScript.

Style HTML Mark Highlights

These CSS rules round the edges of filled highlights drawn with HTML mark elements.

mark[data-hh-highlight-id][data-hh-style="fill"] {
  box-decoration-break: clone;
  -webkit-box-decoration-break: clone;
}
mark[data-hh-highlight-id][data-hh-style="fill"][data-hh-position~="start"] {
  border-radius: 0.2em 0 0 0.2em;
}
mark[data-hh-highlight-id][data-hh-style="fill"][data-hh-position~="end"] {
  border-radius: 0 0.2em 0.2em 0;
}

Alternatives And Related Resources

• penciled: Persistent Text Highlights and Notes in JavaScript
• Interactive Text Annotation and Highlighting with Recogito Text Annotator
• Text Annotation And Highlighting Library – Annotate.js
• Animated Handdrawn Text Annotation Library – Rough Notation