CSS Custom Highlight API

CSS Custom Highlight API

The Custom Highlight API gives you styled text ranges without rewriting the DOM. That is a big deal for search hits, comments, editor decorations, and collaborative cursors where extra wrapper spans become both fragile and expensive.

const range = new Range();
range.setStart(textNode, startOffset);
range.setEnd(textNode, endOffset);

const highlight = new Highlight(range);
CSS.highlights.set('search-hit', highlight);

Why It Beats Wrapper Spans

Wrapper elements mutate the text tree, interfere with selection logic, and make cleanup noisy. Named highlights keep the underlying document intact while letting CSS own how the range looks.

Use Multiple Layers on Purpose

You can model different semantic layers such as search matches, reviewer comments, and presence indicators as separate named highlights. That keeps UI state understandable instead of collapsing everything into one monolithic decoration system.

CSS Stays Simple

Once the range is registered, styling is just CSS. That is the real win: JavaScript decides what is highlighted, while the design system decides how highlight categories look through ::highlight(name).

Cleanup Matters

Treat highlight registration like any other UI state. Update ranges when the underlying text changes and remove stale highlights when the feature that owns them unmounts or the query changes.

---