Text Selection Highlight & Comment — Free JS Snippet

Real-time collaborative annotation — select text, highlight it, attach a comment to the exact words selected — has gone from a Google Docs and Medium specialty feature to a baseline expectation across knowledge-base tools, code review platforms, PDF viewers, and AI writing assistants. Most implementations that look convincing are actually fake: an absolutely-positioned overlay that approximates where the selection was, disconnected from the real text nodes. This snippet builds the genuine version, directly on top of the browser's Selection and Range API, which is the only reliable way to know exactly which characters of text a user selected and to durably mark that exact span.

How selection detection works

A single mouseup listener on document calls window.getSelection() after every mouse release anywhere on the page. If the returned Selection object is collapsed (meaning the user clicked without dragging, so start and end points are identical) or contains no text, the floating toolbar stays hidden. Otherwise, selection.getRangeAt(0) retrieves the first (and, for mouse selections, only) Range — an object representing a specific start and end boundary point within the DOM tree, independent of visual position. The snippet checks docBody.contains(range.commonAncestorContainer) to make sure the selection actually falls inside the annotatable article text, so selecting UI chrome like a button label doesn't trigger the toolbar.

Positioning the toolbar from real geometry

The toolbar's position is not guessed — range.getBoundingClientRect() returns the exact bounding box of the live selection in viewport coordinates, the same rectangle the browser itself uses to paint the blue selection highlight. positionAt() reads that rectangle's left + width / 2 for horizontal centering and top for vertical placement, adds the current scroll offset, and applies it as left/top on a position: fixed element whose CSS transform: translate(-50%, -100%) translateY(-10px) centers it horizontally and floats it just above the selection — the exact technique real editors use, because it tracks the actual selected characters rather than an approximate mouse coordinate.

Highlighting: surroundContents with a fallback

The core, genuinely tricky part of DOM-based highlighting is turning an arbitrary user selection into a wrapped <mark> element. Range.surroundContents(mark) is the native, single-call way to do this — it moves the range's contents inside the new mark node — but it throws a DOMException if the range's boundaries don't cleanly nest inside a single parent (for example, a selection that starts partway through one <span> and ends partway through a different one, spanning multiple inline nodes at different depths). This snippet handles that case explicitly with try/catch: on failure, it falls back to range.extractContents() (which removes the selected content as a DocumentFragment, correctly splitting any partially-selected nodes at the boundaries) followed by appending that fragment inside a new <mark> and calling range.insertNode(mark) to put the wrapper back in place. This two-path approach — try the fast native method, fall back to manual extract-and-reinsert — is the standard, correct way to make in-place DOM highlighting robust against real-world selections that cross element boundaries, which single-call surroundContents alone cannot handle.

Comments: popover input and a persistent indicator

Clicking "Comment" instead of "Highlight" repositions a small textarea-based popover over the same saved range. Saving a non-empty note calls the same wrapRangeInMark() helper (with an extra has-comment class for a slightly deeper highlight color) and stores the note text directly on the <mark> element via mark.dataset.note, then appends a small numbered .comment-dot badge inside the mark so the reader can see at a glance which highlights carry a note. A delegated click listener on the whole article checks e.target.closest('mark.annotation-highlight.has-comment') so clicking any commented highlight — old or newly created — reopens a small note viewer positioned above it, reading the note straight back out of the dataset.note attribute. Because the range is saved as a *cloned* Range object (range.cloneRange()) at the moment of selection, it remains valid and independently usable even after the live browser selection is cleared when the user clicks the toolbar button.