CSS Custom Highlight API

References

• CSS Custom Highlight API MDN Docs

Related

• ::selection
• • The ::selection CSS pseudo-element applies styles to the part of a document that has been highlighted by the user.
• ::spelling-error
• • The ::spelling-error CSS pseudo-element represents a text segment which the user agent has flagged as incorrectly spelled.
• ::grammar-error
• • The ::grammar-error CSS pseudo-element represents a text segment which the user agent has flagged as grammatically incorrect.
• ::target-text
• • The ::target-text CSS pseudo-element represents the text that has been scrolled to if the browser supports text fragments. It allows authors to choose how to highlight the selection of text.
• Range()
• • The Range() interface represents a fragment of a document that can contain nodes and parts of text nodes. A range can be created using the Document.createRange() method. Range objects can also be retrieved by using the getRangeAt() method of the Selection object or the caretRangeFromPoint() method of the Document object.
• text fragments
• • Text fragments allow linking directly to a specific portion of text in a web document, without requiring the author to annotate it with an ID, using particular syntax in the URL fragment. Supporting browsers are free to choose how to draw attention to the linked text. This is useful because it allows web content authors to deep-link to other content they don't control, without relying on the presence of IDs to make that possible. Building on top of that, it could be used to generate more effective content-sharing links for users to pass to one another.

Notes

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.

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 4 structures to style text ranges on a webpage using the CSS Custom Highlight API:

1. Creating Range objects.
2. Creating Highlight objects for these ranges.
3. 1. 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.
   2. You can create multiple highlights for one range - each highlight can be styled differently.
3. Registering the highlights using the HighlightRegistry
4. 1. Once highlights have been created, register them by using the HighlightRegistry available as CSS.highlights.
   2. 1. The registry is a Map-like object used to register highlights by names.
4. Styling the highlights using the ::highlight() pseudo-element.
5. 1. The final step is to style the registered highlights. This is done by using the ::highlight() pseudo element.

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);

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

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

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

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

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

Highlight

The Highlight interface of the CSS Custom Highlight API is used to represent a collection of Range instances to be styled using the API. To style arbitrary ranges in a page, instantiate a new Highlight object, add one or more Range objects to it, and register it using the HighlightRegistry. A Highlight instance is a Set-like object that can hold one or more Range objects.

• Highlight.priority
• • A number that indicates the priority of this Highlight object. When multiple highlights overlap, the browser uses this priority to decide how to style the overlapping parts.
• Highlight.size
• • Returns the range in the Highlight object.
• Highlight.type
• • An enumerated String used to specify the semantic meaning of the highlight. This allows assistive technologies to include this meaning when exposing the highlight to users.
• Methods
• • add()
  • • Add a new range to this highlight.
  • delete()
  • • Remove a range from this highlight.
  • entries()
  • • Returns a new iterator object that contains each range in the highlight object, in insertion order.
  • forEach()
  • • Calls the given callback for once for each range in the highlight object, in insertion order.
  • has()
  • • Returns a Boolean asserting whether a range is present the highlight object or not.
  • keys()
  • • An alias for Highlight.values()
  • values()
  • • Returns a new iterator object that yields the ranges in the highlight object in insertion order.

HighlightRegistry

Used to register Highlight objects to be styled using the API. It is accessed via CSS.highlights. A HighlightRegistry instance is a Map-like object, in which each key is the name string for a custom highlight, and the corresponding value is the associated Highlight object.

• Methods
• • clear()
  • • Remove all Highlight objects from the registry.
  • delete()
  • • Remove the named Highlight object from the registry.
  • entries()
  • • Returns a new iterator object that contains each Highlight object in the registry, in insertion order.
  • forEach()
  • • Calls the given callback once for each Highlight object in the registry, in insertion order.
  • get()
  • • Gets the named Highlight object from the registry.
  • has()
  • • Returns a Boolean asserting whether a Highlight object is present in the registry or not.
  • keys()
  • • An alias for values()
  • set()
  • • Adds the given Highlight object to the registry with the given name, or updates the named Highlight object, if it already exists in the registry.
  • values()
  • • Returns a new iterator object that yields the Highlight objects in registry, in insertion order.