W3cubDocs

/Web APIs

HighlightRegistry

Baseline 2025 *

Newly available

Since ⁨June 2025⁩, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Some parts of this feature may have varying levels of support.

The HighlightRegistry interface of the CSS Custom Highlight API is 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.

Instance properties

The HighlightRegistry interface doesn't inherit any properties.

HighlightRegistry.size Read only: Returns the number of Highlight objects currently registered.

Instance methods

The HighlightRegistry interface doesn't inherit any methods.

HighlightRegistry.clear(): Remove all Highlight objects from the registry.
HighlightRegistry.delete(): Remove the named Highlight object from the registry.
HighlightRegistry.entries(): Returns a new iterator object that contains each Highlight object in the registry, in insertion order.
HighlightRegistry.forEach(): Calls the given callback once for each Highlight object in the registry, in insertion order.
HighlightRegistry.get(): Gets the named Highlight object from the registry.
HighlightRegistry.has(): Returns a boolean asserting whether a Highlight object is present the registry or not.
HighlightRegistry.highlightsFromPoint() Experimental: Returns an array of objects representing the custom highlights applied at a specific point within the viewport.
HighlightRegistry.keys(): An alias for HighlightRegistry.values().
HighlightRegistry.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.
HighlightRegistry.values(): Returns a new iterator object that yields the Highlight objects in the registry, in insertion order.

Examples

Registering a highlight

The following example demonstrates how to create ranges, instantiate a new Highlight object for them, and register the highlight using the HighlightRegistry, to style it on the page:

HTML

<p id="foo">CSS Custom Highlight API</p>

CSS

::highlight(my-custom-highlight) {
  background-color: peachpuff;
}

JavaScript

const text = document.getElementById("foo").firstChild;

if (!CSS.highlights) {
  text.textContent =
    "The CSS Custom Highlight API is not supported in this browser!";
}

// Create a couple of ranges.
const range1 = new Range();
range1.setStart(text, 0);
range1.setEnd(text, 3);

const range2 = new Range();
range2.setStart(text, 21);
range2.setEnd(text, 24);

// Create a custom highlight for these ranges.
const highlight = new Highlight(range1, range2);

// Register the ranges in the HighlightRegistry.
CSS.highlights.set("my-custom-highlight", highlight);

Result

Specifications

Specification
CSS Custom Highlight API Module Level 1> # highlight-registry>

Browser compatibility

	Desktop					Mobile
	Chrome	Edge	Firefox	Opera	Safari	Chrome Android	Firefox for Android	Opera Android	Safari on IOS	Samsung Internet	WebView Android	WebView on iOS
`@@iterator`	105	105	140	91	17.2	105	140	72	17.2	20.0	105	17.2
`HighlightRegistry`	105	105	140	91	17.2	105	140	72	17.2	20.0	105	17.2
`clear`	105	105	140	91	17.2	105	140	72	17.2	20.0	105	17.2
`delete`	105	105	140	91	17.2	105	140	72	17.2	20.0	105	17.2
`entries`	105	105	140	91	17.2	105	140	72	17.2	20.0	105	17.2
`forEach`	105	105	140	91	17.2	105	140	72	17.2	20.0	105	17.2
`get`	105	105	140	91	17.2	105	140	72	17.2	20.0	105	17.2
`has`	105	105	140	91	17.2	105	140	72	17.2	20.0	105	17.2
`highlightsFromPoint`	140	140	No	124	No	140	No	No	No	No	140	No
`keys`	105	105	140	91	17.2	105	140	72	17.2	20.0	105	17.2
`set`	105	105	140	91	17.2	105	140	72	17.2	20.0	105	17.2
`size`	105	105	140	91	17.2	105	140	72	17.2	20.0	105	17.2
`values`	105	105	140	91	17.2	105	140	72	17.2	20.0	105	17.2