CSS Custom Highlight API: mention StaticRange for highlights that outlive DOM changes

Open Beginner friendly
  • Is something wrong?
#46,513 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

@abdul-karim-mia is already working on this.

Since Nov 14, 2026.

  • #46520 by @abdul-karim-mia — open

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
75/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
css, javascript
Domain
documentation

Research direction

Start with the CSS Custom Highlight API page on MDN, in its "Create ranges" section and the "Highlighting search results" example. Read the linked spec section on range invalidation to confirm that live Range objects are updated as the DOM changes and that StaticRange is not. Add a short note in "Create ranges" saying a StaticRange works too, when to prefer it, and that you must recreate it after DOM changes. Done when the note is in place and the wording matches the spec.

Written by the indexing model from the issue text.

Description

Content:WebAPI help wanted
MDN URL

https://developer.mozilla.org/en-US/docs/Web/API/CSS_Custom_Highlight_API

What specific section or headline is this issue about?

"Create ranges", and the "Highlighting search results" example

What information was incorrect, unhelpful, or incomplete?

The page only uses live Range objects. The spec says that updating all Range objects as the DOM changes has a significant performance cost, and that authors who react to DOM changes are strongly encouraged to use StaticRange instead. The page doesn't mention this, and search highlighting is the case where it shows up: the page keeps thousands of ranges while the content changes.

What did you expect to see?

A short note in "Create ranges" that a StaticRange works too, and when to prefer it: static ranges aren't updated when the DOM changes, so they are cheap to keep, but you have to recreate them yourself after a change.

Do you have any supporting links, references, or citations?

https://drafts.csswg.org/css-highlight-api-1/#range-invalidation

Do you have anything more you want to share?

I ran into this while adding search highlighting to a document viewer. The snippet below creates 8,000 ranges over 2,000 paragraphs, registers them, clears the registry, and then makes 2,000 small edits (wrapping one word per paragraph in <mark>). In Chromium 148 the edits take about 380 ms with Range and 1 ms with StaticRange. In WebKit I saw the same pattern in my app on a 1 MB document with 8,387 ranges: 4.2 s with Range, 14 ms with StaticRange. There the ranges had already been dropped, and the cost lasted until they were garbage collected.

document.body.innerHTML = '<p>lorem foo ipsum foo dolor foo sit foo amet</p>'.repeat(2000);
const ranges = [];
for (const p of document.querySelectorAll('p')) {
  const t = p.firstChild;
  for (let i = t.data.indexOf('foo'); i !== -1; i = t.data.indexOf('foo', i + 3)) {
    const r = new Range();
    r.setStart(t, i);
    r.setEnd(t, i + 3);
    ranges.push(r);
    // StaticRange instead:
    // ranges.push(new StaticRange({startContainer: t, startOffset: i, endContainer: t, endOffset: i + 3}));
  }
}
CSS.highlights.set('search', new Highlight(...ranges));
CSS.highlights.clear();

const t0 = performance.now();
for (const p of document.querySelectorAll('p')) {
  const mid = p.firstChild.splitText(p.firstChild.data.indexOf('foo'));
  mid.splitText(3);
  const mark = document.createElement('mark');
  mid.replaceWith(mark);
  mark.append(mid);
}
console.log(performance.now() - t0);
Dominant language
Markdown
Stars
11.1k
Forks
23.3k
Avg merge
2d 14h
Merged PRs (30d)
165

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from mdn/content

All issues in mdn/content

Similar issues

More Documentation issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.