penciled: Persistent Text Highlights and Notes in JavaScript

penciled is a lightweight JavaScript text annotation library that lets your readers highlight passages and attach notes directly to web pages.

Highlights survive page reloads, and readers can edit or remove them through a floating toolbar.

It works with ordinary HTML content, supports custom storage for cross-device access, and includes a headless engine for sites that need their own annotation UI.

Features

• 5 preset highlight colors and custom color palettes.
• Optional hover previews and dotted note indicators.
• Restore annotations from local storage or a custom backend.
• Re-anchor highlights after content changes.
• Render overlapping highlights through the CSS Custom Highlight API.
• Adjust toolbar actions, keyboard shortcuts, labels, and placement.
• Switch between light and dark themes or use a custom CSS theme.
• Use the vanilla JavaScript engine, headless package, or React adapter.

How To Use It

Installation

Install penciled via NPM:

npm install penciled

Basic Usage

Create a container for the text that readers should annotate. Import the library and stylesheet after that container exists. Selecting text opens a floating toolbar, and saved annotations return from localStorage after a reload.

<article id="article">
  <h2>A Short Guide to CSS Grid</h2>
  <p>CSS Grid arranges content in rows and columns.</p>
  <p>Select any sentence to highlight it or attach a note.</p>
</article>

import { annotate } from 'penciled';
import 'penciled/styles.css';
const penciled = annotate('#article');

Direct Browser Import (CDN)

For a page with no build step, load the ES module from a CDN.

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/penciled/dist/styles.css">
<article id="article">
  <p>Select this text and save a highlight.</p>
</article>
<script type="module">
  import { annotate } from 'https://cdn.jsdelivr.net/npm/penciled/+esm';
  annotate('#article');
</script>

Save Annotations for Each Article

Set documentId explicitly in single-page applications, especially when the displayed article changes but the URL does not. The identifier remains fixed for an instance’s lifetime.

const penciled = annotate('#article', {
  documentId: 'css-grid-introduction',
  noteIndicator: 'underline',
  notePreview: 'hover',
});

Save Notes to Your Own Backend

The storage option accepts asynchronous load and save methods. Your server must expose the endpoints and return an array of annotations for each document. A missing document should return an empty array. A failed request must reject the promise. penciled does not retry failed saves.

If loading from a custom adapter fails, the instance disables later saves to protect existing server data. For per-annotation REST endpoints, the adapter can additionally implement create, update, and delete. Those methods replace full-document save for their respective changes.

import { annotate } from 'penciled';
import 'penciled/styles.css';
const storage = {
  async load(documentId) {
    const response = await fetch(`/api/annotations/${encodeURIComponent(documentId)}`);
    if (response.status === 404) return [];
    if (!response.ok) throw new Error('Unable to load annotations');
    return response.json();
  },
  async save(documentId, annotations) {
    const response = await fetch(`/api/annotations/${encodeURIComponent(documentId)}`, {
      method: 'PUT',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(annotations),
    });
    if (!response.ok) throw new Error('Unable to save annotations');
  },
};
const penciled = annotate('#article', {
  documentId: 'css-grid-introduction',
  storage,
  onError: (error) => console.error('Annotation storage failed', error),
});

Use Read-Only Highlights

readOnly locks the reader-facing controls while keeping annotations visible. The example reads any annotations previously stored for this document ID.

To load publisher annotations, use a custom storage adapter. To lock individual entries, set editable: false on those annotations. Instance methods can edit records even when readers cannot.

annotate('#article', {
  documentId: 'editorial-review',
  readOnly: true,
  noteIndicator: 'underline',
});

Manage and Export Annotations

Wait for ready before reading stored annotations. Use update() to change the returned records, since getAll() and other read methods return copies. Exported data includes orphaned annotations whose original text is no longer identifiable.

const penciled = annotate('#article', { documentId: 'css-grid-introduction' });
await penciled.ready;
const annotations = penciled.getAll();
if (annotations.length) {
  penciled.update(annotations[0].id, {
    color: 'green',
    note: 'Review this paragraph again.',
  });
}
const backup = penciled.export();
console.log(JSON.stringify(backup));
// Merge annotations from a previously exported JSON object.
penciled.import(backup);

Use penciled with React

import { Annotatable } from 'penciled/react';
import 'penciled/styles.css';
export function ReadingPage({ article }) {
  return (
    <Annotatable as="article" options={{ documentId: article.id }}>
      <h1>{article.title}</h1>
      <p>{article.summary}</p>
    </Annotatable>
  );
}

Create a Custom Toolbar with Headless Mode

penciled/headless handles anchoring, highlights, storage, and events, but does not create any floating controls. The example below adds a Highlight button that appears near a new text selection.

The data-penciled attribute keeps clicks on the button from dismissing the selection. Import the default stylesheet for highlight colors, or write your own ::highlight() rules.

import { annotate } from 'penciled/headless';
import 'penciled/styles.css';
const penciled = annotate('#article');
const button = document.createElement('button');
button.textContent = 'Highlight';
button.hidden = true;
button.style.position = 'fixed';
button.setAttribute('data-penciled', '');
document.body.append(button);
let selected = null;
penciled.on('select', (context) => {
  selected = context;
  if (!context || context.annotation || !context.editable) {
    button.hidden = true;
    return;
  }
  const rect = context.range.getBoundingClientRect();
  button.style.left = `${rect.left}px`;
  button.style.top = `${Math.max(8, rect.top - 40)}px`;
  button.hidden = false;
});
button.addEventListener('mousedown', (event) => event.preventDefault());
button.addEventListener('click', () => {
  if (selected?.editable && !selected.annotation) {
    penciled.create(selected.range, { color: 'yellow' });
  }
  button.hidden = true;
  getSelection()?.removeAllRanges();
});

All Configuration Options

Data and Storage

Colors and Appearance

Interaction and Accessibility

The toolbar supports arrow-key navigation and Escape to close it. Annotation navigation shortcuts announce locations to screen readers. Keep the toolbar shortcut active with openOnSelect: false, unless another control can open it.

Event Callback Options

Each callback receives the event payload and can be registered during initialization or later through on().

Instance Properties and Methods

annotate() returns an Annotator instance. Read methods return annotation copies.

Properties

Reading and Editing

Navigation and Lifecycle

Events

Listeners registered with on() use the event names without the on prefix.

const stopListening = penciled.on('create', (annotation) => {
  console.log(annotation.quote);
});
// Call when this listener is no longer needed.
stopListening();

Styling and Customization

CSS Custom Properties

-root {
  --penciled-yellow: light-dark(#fef08a, #854d0e80);
  --penciled-radius: 8px;
  --penciled-accent: light-dark(#4f46e5, #a5b4fc);
  --penciled-accent-fg: light-dark(#fff, #1e1b4b);
}

Public CSS Attribute Selectors

Highlight Selectors

The CSS Custom Highlight API paints ::highlight(penciled-<color>) for each color, ::highlight(penciled-<color>-noted) for highlighted notes when the underline indicator is enabled, and ::highlight(penciled-active) for the active annotation.

Only CSS properties permitted by ::highlight() apply. Borders, padding, and border radius cannot style highlighted ranges.

-:highlight(penciled-yellow),
-:highlight(penciled-yellow-noted) {
  background-color: #fde04780;
}
-:highlight(penciled-yellow-noted) {
  text-decoration: underline dotted 2px;
}

Headless Option Scope

The headless package accepts documentId, storage, saveDelay, observe, all seven event callbacks, colors (string names only), defaultColor, readOnly, and noteIndicator. UI-specific options, including theme, actions, labels, placement, shortcuts, maxNoteLength, and notePreview, are unavailable in headless mode.

Alternatives & Related Resources

• Interactive Text Annotation and Highlighting with Recogito Text Annotator
• Text Annotation And Highlighting Library – Annotate.js
• Underline/Highlight/Strike Text With The textAnnotator Library
• Hightlight Content Selection For The Web – Web Highlighter
• Animated Handdrawn Text Annotation Library – Rough Notation