CSS Custom Highlight API

The CSS Custom Highlight API provides a mechanism for styling arbitrary text ranges on a document by using JavaScript to create the ranges, and CSS to style them.

Concepts and usage

Styling text ranges on a webpage can be very useful. For example, text editing web apps highlight spelling or grammar errors, and code editors highlight syntax errors.

The CSS Custom Highlight API extends the concept of other highlight pseudo-elements such as ::selection, ::spelling-error, ::grammar-error, and ::target-text by providing a way to create and style arbitrary Range objects, rather than being limited to browser-defined ranges.

Using the CSS Custom Highlight API, you can programmatically create text ranges and highlight them without affecting the DOM structure in the page.

There are four steps to style text ranges on a webpage using the CSS Custom Highlight API:

Creating Range objects.
Creating Highlight objects for these ranges.
Registering the highlights using the HighlightRegistry.
Styling the highlights using the ::highlight() pseudo-element.

Create ranges

The first step is to define the text ranges that you want to style by creating Range objects in JavaScript. For example:

const parentNode = document.getElementById("foo");

const range1 = new Range();
range1.setStart(parentNode, 10);
range1.setEnd(parentNode, 20);

const range2 = new Range();
range2.setStart(parentNode, 40);
range2.setEnd(parentNode, 60);

Create highlights

The second step is to instantiate Highlight objects for your text ranges.

Multiple ranges can be associated to one highlight. If you want to highlight multiple pieces of text the same way, you need to create a single highlight and initialize it with the corresponding ranges.

const highlight = new Highlight(range1, range2);

But you can also create as many highlights as you need. For example, if you are building a collaborative text editor where each user gets a different text color, then you can create one highlight per user, as seen in the code snippet below:

const user1Highlight = new Highlight(user1Range1, user1Range2);
const user2Highlight = new Highlight(user2Range1, user2Range2, user2Range3);

Each highlight can be styled differently.

Register highlights

Once highlights have been created, register them by using the HighlightRegistry available as CSS.highlights.

The registry is a Map-like object used to register highlights by names, as seen below:

CSS.highlights.set("user-1-highlight", user1Highlight);
CSS.highlights.set("user-2-highlight", user2Highlight);

In the above code snippet, the user-1-highlight and user-2-highlight strings are custom identifiers that can be used in CSS to apply styles to the registered highlights.

You can register as many highlights as you need in the registry, as well as remove highlights and clear the entire registry.

// Remove a single highlight from the registry.
CSS.highlights.delete("user-1-highlight");

// Clear the registry.
CSS.highlights.clear();

Style highlights

The final step is to style the registered highlights. This is done by using the ::highlight() pseudo-element. For example, to style the user-1-highlight highlight registered in the previous step:

css

::highlight(user-1-highlight) {
  background-color: yellow;
  color: black;
}

Interfaces

Highlight: This interface is used to represent a collection of ranges to be styled on a document.
HighlightRegistry: Accessible via CSS.highlights, this Map-like object is used to register highlights with custom identifiers.

Examples

Highlighting search results

This example shows how to use the CSS Custom Highlight API to highlight search results.

HTML

The HTML code snippet below defines a search field and an article with a few paragraphs of text:

html

<label>Search within text <input id="query" type="text" /></label>
<article>
  <p>
    Maxime debitis hic, delectus perspiciatis laborum molestiae labore,
    deleniti, quam consequatur iure veniam alias voluptas nisi quo. Dolorem
    eaque alias, quo vel quas repudiandae architecto deserunt quidem, sapiente
    laudantium nulla.
  </p>
  <p>
    Maiores odit molestias, necessitatibus doloremque dolor illum reprehenderit
    provident nostrum laboriosam iste, tempore perferendis! Ab porro neque esse
    voluptas libero necessitatibus fugiat, ex, minus atque deserunt veniam
    molestiae tempora? Vitae.
  </p>
  <p>
    Dolorum facilis voluptate eaque eius similique ducimus dignissimos assumenda
    quos architecto. Doloremque deleniti non exercitationem rerum quam alias
    harum, nisi obcaecati corporis temporibus vero sapiente voluptatum est
    quibusdam id ipsa.
  </p>
</article>

JavaScript

JavaScript is used to listen to the input event on the search field. When the event is fired, the code locates matches for the input text in the article text. It then creates ranges for the matches, and uses the CSS Custom Highlight API to create and register a search-results highlight object:

const query = document.getElementById("query");
const article = document.querySelector("article");

// Find all text nodes in the article. We'll search within
// these text nodes.
const treeWalker = document.createTreeWalker(article, NodeFilter.SHOW_TEXT);
const allTextNodes = [];
let currentNode = treeWalker.nextNode();
while (currentNode) {
  allTextNodes.push(currentNode);
  currentNode = treeWalker.nextNode();
}

// Listen to the input event to run the search.
query.addEventListener("input", () => {
  // If the CSS Custom Highlight API is not supported,
  // display a message and bail-out.
  if (!CSS.highlights) {
    article.textContent = "CSS Custom Highlight API not supported.";
    return;
  }

  // Clear the HighlightRegistry to remove the
  // previous search results.
  CSS.highlights.clear();

  // Clean-up the search query and bail-out if
  // if it's empty.
  const str = query.value.trim().toLowerCase();
  if (!str) {
    return;
  }

  // Iterate over all text nodes and find matches.
  const ranges = allTextNodes
    .map((el) => {
      return { el, text: el.textContent.toLowerCase() };
    })
    .map(({ text, el }) => {
      const indices = [];
      let startPos = 0;
      while (startPos < text.length) {
        const index = text.indexOf(str, startPos);
        if (index === -1) break;
        indices.push(index);
        startPos = index + str.length;
      }

      // Create a range object for each instance of
      // str we found in the text node.
      return indices.map((index) => {
        const range = new Range();
        range.setStart(el, index);
        range.setEnd(el, index + str.length);
        return range;
      });
    });

  // Create a Highlight object for the ranges.
  const searchResultsHighlight = new Highlight(...ranges.flat());

  // Register the Highlight object in the registry.
  CSS.highlights.set("search-results", searchResultsHighlight);
});

CSS

Finally, the ::highlight() pseudo-element is used in CSS to style the highlights:

css

::highlight(search-results) {
  background-color: #f06;
  color: white;
}

Result

The result is shown below. Type text within the search field to highlight matches in the article:

Specifications

Specification
CSS Custom Highlight API Module Level 1