# CSS Custom Highlight API Module Level 1

## Editor’s Draft, 1 January 1970

Specification Metadata

This version:
  https://drafts.csswg.org/css-highlight-api-1/
Editors:
  Florian Rivoal (On behalf of Bloomberg)
  Sanket Joshi (Microsoft Corporation)
  Theresa O'Connor (Apple Inc.)
Issue Tracking:
  GitHub Issues
Suggest an Edit for this Spec:
  GitHub Editor

Copyright © 1970 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.

## Abstract

This CSS module describes a mechanism for styling arbitrary ranges of a document identified by script.

CSS is a language for describing the rendering of structured documents (such as HTML and XML) on screen, on paper, etc.

## Status of this document

This is a public copy of the editors’ draft. It is provided for discussion only and may change at any moment. Its publication here does not imply endorsement of its contents by W3C. Don’t cite this document other than as work in progress.

GitHub Issues are preferred for discussion of this specification. When filing an issue, please put the text “css-highlight-api” in the title, preferably like this: “[css-highlight-api] …summary of comment…”. All issues and comments are archived, and there is also a historical archive.

This document was produced by the CSS Working Group.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 March 2019 W3C Process Document.

## 1. Introduction

This section is non-normative.

The Custom Highlight API extends the concept of highlight pseudo-elements (see CSS Pseudo-Elements 4 §3 Highlight Pseudo-elements) by providing a way for web developers to style the text of arbitrary Range objects, rather than being limited to the user agent defined ::selection, ::inactive-selection, ::spelling-error, and '::grammar-error'. This is useful in a variety of scenarios, including editing frameworks that wish to implement their own selection, find-on-page over virtualized documents, multiple selection to represent online collaboration, or spellchecking frameworks.

The Custom Highlight API provides a programmatic way of adding and removing highlights that do not affect the underlying DOM structure, but instead applies styles to text based on range objects, accessed via the ::highlight() pseudo element.

The following code uses the ::highlight() pseudo-element to apply a yellow background and blue foreground color to the text One two. It does so by adding a `Highlight` to the `HighlightsRegister` (both of these are new concepts introduced by this specification). The `Highlight` will contain a `Range` whose boundary points surround the text One two.

    <style>
    :root::highlight(example-highlight) {
      background-color: yellow;
      color: blue;
    }
    </style>
    <body><span>One </span><span>two </span><span>three…</span>
    <script>
    let r = new Range();
    r.setStart(document.body, 0);
    r.setEnd(document.body, 2);

    CSS.highlights.add(new Highlight("example-highlight", r));
    </script>

The result would look like:

One Two three…

## 2. Module Interactions

This module depends on the Infra Standard [INFRA] and on WebIDL [WebIDL].

It assumes general familiarity with CSS and with the DOM Standard [DOM], and specifically extends the mechanisms defined in CSS Pseudo-Elements Module Level 4 [css-pseudo-4] to handle highlight pseudo-elements. The Selectors Level 4 [selectors-4] specification defines how pseudo-elements work in general.

See References for a full list of dependencies.

Note: This draft is an early version. As it matures, the CSS-WG could decide to keep it as an independent module, or might prefer to fold it into [css-pseudo-4], or a later version of that module.

## 3. Setting up Custom Highlights

### 3.1. Creating Custom Highlights

A custom highlight is a named collection of ranges representing portions of a document. They do not necessarily fit into the element tree, and can arbitrarily cross element boundaries without honoring its nesting structure. They can be used to affect the appearance of these portions of the document (see § 4 Styling Custom Highlights), or to handle to events associated with them (see § 6 Event Handling).

Custom highlights are represented by `Highlight` objects, setlike objects whose set entries are `AbstractRange` objects. Ranges can be added to a custom highlight either by passing them to its constructor, or by using the usual API of setlike objects to manipulate its set entries.

Note: As the ranges in a custom highlight are `AbstractRange` objects, authors can chose between using `Range` objects and `StaticRange` objects. See § 5.2 Range Updating and Invalidation for more details about this choice and its implications.

The name of a custom highlight is represented by its `name` attribute, which must must be a valid <ident-token>.

    [Exposed=Window]
    interface Highlight {
      constructor(CSSOMString name, AbstractRange... initialRanges);
      setlike<AbstractRange>;
      attribute double priority;
      readonly attribute CSSOMString name;
    };

See § 4.2.4 Priority of Overlapping Highlights for more information on the `priority` attribute.

When the `Highlight(CSSOMString name, AbstractRange... initialRanges)` constructor is invoked, run the following steps:

1. Let highlight be the new `Highlight` object.
2. If `name` does not parse as an <ident-token>, then throw a `"SyntaxError"`.
3. Let nameArg be the result of converting `name` to an ECMAScript value.
4. Set highlight’s `name` to nameArg
5. Set highlight’s `priority` to `0`.
6. For each range of `initialRanges`, let rangeArg be the result of converting range to an ECMAScript value, then run the steps for a built-in setlike add function, with highlight as the `this` value, and rangeArg as the argument.
7. Return highlight.

### 3.2. Registering Custom Highlights

In order to have any effect, custom highlights then needs to be registered it into the highlights register.

The highlights register is accessed via the `highlights` attribute of the `CSS` namespace, and represents all the custom highlights registered for the current global object’s associated Document. It is a setlike, and can be updated using the usual methods. It’s set entries is initially empty.

A custom highlight is said to be registered if it is in the highlights register. It stops being registered if it is later removed.

    partial namespace CSS {
      readonly attribute HighlightsRegister highlights;
    };

    [Exposed=Window]
    interface HighlightsRegister {
      setlike<Highlight>;
      HighlightsRegister add(Highlight value);
    };

To register a custom highlight, invoke the `add()` of the highlights register with the custom highlight as the argument.

When invoked, the `add(Highlight value)` method must run these steps:

1. If there is already a set entry with the same `name` as the `name` of `value`, then throw an `"OperationError"`.

2. Let valueArg be the result of converting `value` to an ECMAScript value.

3. Let result be the result of running the steps for a built-in setlike add function, with the context object as the `this` value and with valueArg as the argument.

4. Return result.

## 4. Styling Custom Highlights

### 4.1. The Custom Highlight Pseudo-element: ::highlight()

The ::highlight(<highlight-name>) pseudo-element (also known as the custom highlight pseudo-element) represents the portion of a document that is being contained or partially contained in all the ranges of the registered custom highlight with the name <highlight-name>, if any. <highlight-name> must be a valid CSS <ident-token>.

### 4.2. Processing Model

#### 4.2.1. Applicable Properties

Custom highlight pseudo-elements, like the built-in highlight pseudo-elements, can only be styled with a limited set of properties. See CSS Pseudo-Elements 4 §3.2 Styling Highlights for the full list.

#### 4.2.2. Cascading and Inheritance

The cascading and inheritance of custom highlight pseudo-elements is handled identically to that of the built-in highlight pseudo-elements, as defined in CSS Pseudo-Elements 4 §3.4 Cascading and Per-Element Highlight Styles.

#### 4.2.3. Painting

The painting of custom highlights is also handled identically to that of the built-in highlight pseudo-elements, as specified in CSS Pseudo-Elements 4 §3.3 Area of a Highlight and CSS Pseudo-Elements 4 §3.5 Painting the Highlight, with the following clarifications:

- Collapsed ranges are not rendered.
- Overlapping ranges within a single custom highlight are rendered as if a single range representing the union of the overlapping ones had been specified.
  The following example renders in a single highlight with semi-transparent blue background, not two overlapping ones which can be seen through each other.

      <style>
        ::highlight(sample) { background-color: rgba(0, 0, 255, 0.3); }
      </style>
      <body>Lorem Ipsum.
      <script>
        let r1 = new Range();
        r1.setStart(document.body, 1);
        r1.setEnd(document.body, 5);

        let r2 = new Range();
        r2.setStart(document.body, 3);
        r2.setEnd(document.body, 7);

        CSS.highlights.add(new Highlight("sample", r1, r2));
      </script>

  In other words, this rendering would be correct:

  Lorem Ipsum.

  However, this one would be incorrect:

  Lorem Ipsum.
- The highlight overlays of the custom highlights are above those of the built-in highlight pseudo-elements in the stacking order described in CSS Pseudo-Elements 4 §3.5 Painting the Highlight.
- The relative stacking order of the highlight overlays of multiple custom highlights is defined by their priority (see § 4.2.4 Priority of Overlapping Highlights).

#### 4.2.4. Priority of Overlapping Highlights

A custom highlight's `priority` attribute defines its priority. This is used to determine the stacking order of the corresponding highlight overlay during painting operations (see § 4.2.3 Painting). A higher priority results in being above in the stacking order.

When two ore more custom highlights have the same numerical priority, the one most recently registered has the higher effective priority.

should negative numbers mean stacking below the built-in highlight pseudo-elements? <https://github.com/w3c/csswg-drafts/issues/4593>

Should priority be an (unsigned) integer instead? That would make comparisons more reliable, but would likely lead to numbering reminiscent of BASIC line numbers. <https://github.com/w3c/csswg-drafts/issues/4592>

Should we drop priority by numbers entirely, and replace it with some other ordering mechanism? Experience with BASIC line number or z-index does not give much confidence that ordering by number is a good idea. Is placing in an ordered data-structure better? Should authors be able to express a desired to be placed above/below other named highlights, and let the UA figure it out? <https://github.com/w3c/csswg-drafts/issues/4591>

Should the built-in highlight pseudo-elements be exposed as well, so that they too can be reordered, and so that they can be interleaved with custom ones freely? <https://github.com/w3c/csswg-drafts/issues/4594>

    <style>
      p::highlight(foo) {
        color:blue;
        background-color:yellow;
      }
      p::highlight(bar) {
        background-color:orange;
      }
    </style>
    <body>Some text
    <script>
      let r1 = new Range();
      r1.setStart(document.body, 0);
      r1.setEnd(document.body, 6);

      let r2 = new Range();
      r2.setStart(document.body, 3);
      r2.setEnd(document.body, 9);

      CSS.highlights.add(new Highlight("foo", r1));
      CSS.highlights.add(new Highlight("bar", r2));
    </script>

As there are no priorities set (i.e. there is a tie between `rg1` and `rg2`), the custom highlights' styles are stacked in order of insertion into the highlights register. The rendered results will have "Som" with blue text on yellow background, "e t" with blue text on orange background, and "ext" with the default color on orange background.

Some text

Setting `rg1.priority = 1;` would cause `rg1` to stack higher than `rg2`, which would result in "Some t" being blue on yellow, and "ext" being default color on orange.

Some text

## 5. Responding to Changes

### 5.1. Repaints

The addition or removal of a custom highlight in the highlights register, or of a range in a [registered=] custom highlight, must cause the User Agent to reevaluate the rendering, and to repaint if appropriate.

The User Agent must also repaint highlights as needed in response to changes by the author to the `priority`, or to the boundary points of `Range`s of a registered custom highlight.

How should we specify the timing (and synchronicity) of this reevaluation? <https://github.com/w3c/csswg-drafts/issues/4596>

### 5.2. Range Updating and Invalidation

Authors can build custom highlights using either `Range`s or `StaticRange`s.

The resulting custom highlight represents the same parts of the document, and can be styled identically. However, the behavior is different in case the underlying document is modified.

`Range`s are live ranges. The User Agent will adjust the boundary points of `Range`s in response to DOM changes overlapping the range or at its boundary, and repaint accordingly. Boundary points of live ranges can also be changed by the author.

On the other hand, the User Agent must not adjust the boundary points of `StaticRange`s in response to DOM changes, nor can they be modified by the author after creation.

Updating all `Range` objects as the DOM is modified has a significant performance cost. Authors who intend to observe DOM changes and react to them by adjusting or recreating the ranges in their custom highlights are strongly encouraged to user `StaticRange`s in order to avoid this costly but unnecessary step.

Conversedly, authors who use `StaticRange`s should observe and react to DOM changes, by discarding stale ranges or custom highlights and recreating new ones.

When computing how to render the document, if start node or end node of any range in the highlights register refer to a `Node` which is no longer in a document tree, the User Agent must ignored that range. If the start offset or end offset of any range are greater than the corresponding node’s length, The User Agent must behave as if it was equal to that length.

As far as I am aware, prior uses of `StaticRange`s were for ranges created by the User Agent and passed to the author. Here, it’s the other way around, which raises (for the first time?) the question of invalidation of static ranges. Can the above work? Is it Fast enough that it’s worth distinguishing static and live ranges? Would some alternative handling be better? <https://github.com/w3c/csswg-drafts/issues/4597>

The interaction of `StaticRange`s in a custom highlight and [css-contain-2] seems problematic: on a fully contained element, you should expect that DOM changes to descendants of that element will not cause invalidation and restyling/repainting of elements outside the contained one. However, if a static range has a boundary point inside the contained subtree and another boundary point outside of it, and the DOM in the contained subtree is changed so that the boundary point inside no longer points to a valid node, the whole range should be ignored, which would affect painting outside the contained subtree. Is this a weakness of style containment, or of the invalidation logic above, or something else? <https://github.com/w3c/csswg-drafts/issues/4598>

## 6. Event Handling

Section on Events TBD, based on https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/master/highlight/events-explainer.md

should custom highlights have a dedicated event handling mechanism, or should that be added to pseudo-elements in general?

## Appendix A. Privacy and Security Considerations

This section is non-normative.

Provide summary of Privacy and Security Considerations for this specification

Note: The TAG has developed a self-review questionnaire to help editors and Working Groups evaluate the risks introduced by their specifications. This document was used in preparing this section.

## Appendix B. Acknowledgements

This section is non-normative.

Acknowledge people (other than editors) who deserve credit for this.

## Conformance

### Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with `class="example"`, like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with `class="note"`, like this:

Note, this is an informative note.

Advisements are normative sections styled to evoke special attention and are set apart from other normative text with `<strong class="advisement">`, like this: UAs MUST provide an accessible alternative.

### Conformance classes

Conformance to this specification is defined for three conformance classes:

style sheet
  A CSS style sheet.
renderer
  A UA that interprets the semantics of a style sheet and renders documents that use them.
authoring tool
  A UA that writes a style sheet.

A style sheet is conformant to this specification if all of its statements that use syntax defined in this module are valid according to the generic CSS grammar and the individual grammars of each feature defined in this module.

A renderer is conformant to this specification if, in addition to interpreting the style sheet as defined by the appropriate specifications, it supports all the features defined by this specification by parsing them correctly and rendering the document accordingly. However, the inability of a UA to correctly render a document due to limitations of the device does not make the UA non-conformant. (For example, a UA is not required to render color on a monochrome monitor.)

An authoring tool is conformant to this specification if it writes style sheets that are syntactically correct according to the generic CSS grammar and the individual grammars of each feature in this module, and meet all other conformance requirements of style sheets as described in this module.

### Requirements for Responsible Implementation of CSS

The following sections define several conformance requirements for implementing CSS responsibly, in a way that promotes interoperability in the present and future.

#### Partial Implementations

So that authors can exploit the forward-compatible parsing rules to assign fallback values, CSS renderers must treat as invalid (and ignore as appropriate) any at-rules, properties, property values, keywords, and other syntactic constructs for which they have no usable level of support. In particular, user agents must not selectively ignore unsupported property values and honor supported values in a single multi-value property declaration: if any value is considered invalid (as unsupported values must be), CSS requires that the entire declaration be ignored.

#### Implementations of Unstable and Proprietary Features

To avoid clashes with future stable CSS features, the CSSWG recommends following best practices for the implementation of unstable features and proprietary extensions to CSS.

#### Implementations of CR-level Features

Once a specification reaches the Candidate Recommendation stage, implementers should release an unprefixed implementation of any CR-level feature they can demonstrate to be correctly implemented according to spec, and should avoid exposing a prefixed variant of that feature.

To establish and maintain the interoperability of CSS across implementations, the CSS Working Group requests that non-experimental CSS renderers submit an implementation report (and, if necessary, the testcases used for that implementation report) to the W3C before releasing an unprefixed implementation of any CSS features. Testcases submitted to W3C are subject to review and correction by the CSS Working Group.

Further information on submitting testcases and implementation reports can be found from on the CSS Working Group’s website at http://www.w3.org/Style/CSS/Test/. Questions should be directed to the public-css-testsuite@w3.org mailing list.

## Index

### Terms defined by this specification

- add(value), in §3.2
- constructor(name), in §3.1
- constructor(name, ...initialRanges), in §3.1
- custom highlight, in §3.1
- custom highlight pseudo-element, in §4.1
- Highlight, in §3.1
- ::highlight(<highlight-name>), in §4.1
- <highlight-name>, in §4.1
- Highlight(name), in §3.1
- Highlight(name, ...initialRanges), in §3.1
- highlights, in §3.2
- highlights register, in §3.2
- HighlightsRegister, in §3.2
- name
  - attribute for Highlight, in §3.1
  - dfn for custom highlight, in §3.1
- priority
  - attribute for Highlight, in §3.1
  - definition of, in §4.2.4
- registered, in §3.2

https://drafts.csswg.org/css-cascade-4/#cascade Referenced in:

- 4.2.2. Cascading and Inheritance

https://drafts.csswg.org/css-cascade-4/#inheritance Referenced in:

- 4.2.2. Cascading and Inheritance

https://drafts.csswg.org/css-contain-1/#style-containment Referenced in:

- 5.2. Range Updating and Invalidation

https://drafts.csswg.org/css-pseudo-4/#selectordef-inactive-selection Referenced in:

- 1. Introduction

https://drafts.csswg.org/css-pseudo-4/#selectordef-selection Referenced in:

- 1. Introduction

https://drafts.csswg.org/css-pseudo-4/#selectordef-spelling-error Referenced in:

- 1. Introduction

https://drafts.csswg.org/css-pseudo-4/#highlight-overlay Referenced in:

- 4.2.3. Painting (2)
- 4.2.4. Priority of Overlapping Highlights

https://drafts.csswg.org/css-pseudo-4/#highlight-pseudo-element Referenced in:

- 1. Introduction
- 2. Module Interactions
- 4.2.1. Applicable Properties
- 4.2.2. Cascading and Inheritance
- 4.2.3. Painting (2)
- 4.2.4. Priority of Overlapping Highlights (2)

https://drafts.csswg.org/css-syntax-3/#typedef-ident-token Referenced in:

- 3.1. Creating Custom Highlights (2)
- 4.1. The Custom Highlight Pseudo-element: ::highlight()

https://drafts.csswg.org/css-syntax-3/#css-parse-something-according-to-a-css-grammar Referenced in:

- 3.1. Creating Custom Highlights

https://drafts.csswg.org/cssom-1/#namespacedef-css Referenced in:

- 3.2. Registering Custom Highlights (2)

https://drafts.csswg.org/cssom-1/#cssomstring Referenced in:

- 3.1. Creating Custom Highlights (2)

https://dom.spec.whatwg.org/#abstractrange Referenced in:

- 3.1. Creating Custom Highlights (2) (3) (4)

https://dom.spec.whatwg.org/#node Referenced in:

- 5.2. Range Updating and Invalidation

https://dom.spec.whatwg.org/#range Referenced in:

- 1. Introduction
- 3.1. Creating Custom Highlights
- 5.1. Repaints
- 5.2. Range Updating and Invalidation (2) (3) (4)

https://dom.spec.whatwg.org/#staticrange Referenced in:

- 3.1. Creating Custom Highlights
- 5.2. Range Updating and Invalidation (2) (3) (4) (5) (6)

https://dom.spec.whatwg.org/#concept-range-bp Referenced in:

- 5.1. Repaints
- 5.2. Range Updating and Invalidation (2) (3)

https://dom.spec.whatwg.org/#range-collapsed Referenced in:

- 4.2.3. Painting

https://dom.spec.whatwg.org/#contained Referenced in:

- 4.1. The Custom Highlight Pseudo-element: ::highlight()

https://dom.spec.whatwg.org/#context-object Referenced in:

- 3.2. Registering Custom Highlights

https://dom.spec.whatwg.org/#concept-range-end-node Referenced in:

- 5.2. Range Updating and Invalidation

https://dom.spec.whatwg.org/#concept-range-end-offset Referenced in:

- 5.2. Range Updating and Invalidation

https://dom.spec.whatwg.org/#in-a-document-tree Referenced in:

- 5.2. Range Updating and Invalidation

https://dom.spec.whatwg.org/#concept-node-length Referenced in:

- 5.2. Range Updating and Invalidation (2)

https://dom.spec.whatwg.org/#concept-live-range Referenced in:

- 5.2. Range Updating and Invalidation (2)

https://dom.spec.whatwg.org/#partially-contained Referenced in:

- 4.1. The Custom Highlight Pseudo-element: ::highlight()

https://dom.spec.whatwg.org/#concept-range Referenced in:

- 1. Introduction
- 3.1. Creating Custom Highlights (2) (3)
- 4.1. The Custom Highlight Pseudo-element: ::highlight()
- 4.2.3. Painting (2)
- 5.1. Repaints
- 5.2. Range Updating and Invalidation (2) (3) (4) (5)

https://dom.spec.whatwg.org/#concept-range-start-node Referenced in:

- 5.2. Range Updating and Invalidation

https://dom.spec.whatwg.org/#concept-range-start-offset Referenced in:

- 5.2. Range Updating and Invalidation

https://html.spec.whatwg.org/multipage/window-object.html#concept-document-window Referenced in:

- 3.2. Registering Custom Highlights

https://html.spec.whatwg.org/multipage/webappapis.html#current-global-object Referenced in:

- 3.2. Registering Custom Highlights

https://drafts.csswg.org/selectors-4/#pseudo-element Referenced in:

- 2. Module Interactions

https://heycam.github.io/webidl/#Exposed Referenced in:

- 3.1. Creating Custom Highlights
- 3.2. Registering Custom Highlights

https://heycam.github.io/webidl/#operationerror Referenced in:

- 3.2. Registering Custom Highlights

https://heycam.github.io/webidl/#syntaxerror Referenced in:

- 3.1. Creating Custom Highlights

https://heycam.github.io/webidl/#dfn-convert-idl-to-ecmascript-value Referenced in:

- 3.1. Creating Custom Highlights (2)
- 3.2. Registering Custom Highlights

https://heycam.github.io/webidl/#idl-double Referenced in:

- 3.1. Creating Custom Highlights

https://heycam.github.io/webidl/#dfn-set-entries Referenced in:

- 3.1. Creating Custom Highlights (2)
- 3.2. Registering Custom Highlights (2)

https://heycam.github.io/webidl/#dfn-setlike Referenced in:

- 3.1. Creating Custom Highlights (2)
- 3.2. Registering Custom Highlights

https://heycam.github.io/webidl/#dfn-throw Referenced in:

- 3.1. Creating Custom Highlights
- 3.2. Registering Custom Highlights

### Terms defined by reference

- [css-cascade-4] defines the following terms:
  - cascade
  - inheritance
- [css-contain-1] defines the following terms:
  - style containment
- [css-pseudo-4] defines the following terms:
  - ::inactive-selection
  - ::selection
  - ::spelling-error
  - highlight overlay
  - highlight pseudo-element
- [css-syntax-3] defines the following terms:
  - <ident-token>
  - parse
- [cssom-1] defines the following terms:
  - CSS
  - CSSOMString
- [DOM] defines the following terms:
  - AbstractRange
  - Node
  - Range
  - StaticRange
  - boundary point
  - collapsed
  - contained
  - context object
  - end node
  - end offset
  - in a document tree
  - length
  - live ranges
  - partially contained
  - range
  - start node
  - start offset
- [HTML] defines the following terms:
  - associated document
  - current global object
- [selectors-4] defines the following terms:
  - pseudo-element
- [WebIDL] defines the following terms:
  - Exposed
  - OperationError
  - SyntaxError
  - converted to an ecmascript value
  - double
  - set entries
  - setlike
  - throw

## References

### Normative References

[CSS-CASCADE-4]
  Elika Etemad; Tab Atkins Jr.. CSS Cascading and Inheritance Level 4. 28 August 2018. CR. URL: https://www.w3.org/TR/css-cascade-4/
[CSS-CONTAIN-1]
  Tab Atkins Jr.; Florian Rivoal. CSS Containment Module Level 1. 30 April 2019. CR. URL: https://www.w3.org/TR/css-contain-1/
[CSS-PSEUDO-4]
  Daniel Glazman; Elika Etemad; Alan Stearns. CSS Pseudo-Elements Module Level 4. 25 February 2019. WD. URL: https://www.w3.org/TR/css-pseudo-4/
[CSS-SYNTAX-3]
  Tab Atkins Jr.; Simon Sapin. CSS Syntax Module Level 3. 20 February 2014. CR. URL: https://www.w3.org/TR/css-syntax-3/
[CSSOM-1]
  Simon Pieters; Glenn Adams. CSS Object Model (CSSOM). 17 March 2016. WD. URL: https://www.w3.org/TR/cssom-1/
[DOM]
  Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[HTML]
  Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[INFRA]
  Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
[RFC2119]
  S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[SELECTORS-4]
  Elika Etemad; Tab Atkins Jr.. Selectors Level 4. 21 November 2018. WD. URL: https://www.w3.org/TR/selectors-4/
[WebIDL]
  Boris Zbarsky. Web IDL. 15 December 2016. ED. URL: https://heycam.github.io/webidl/

## IDL Index

    [Exposed=Window]
    interface Highlight {
      constructor(CSSOMString name, AbstractRange... initialRanges);
      setlike<AbstractRange>;
      attribute double priority;
      readonly attribute CSSOMString name;
    };

    partial namespace CSS {
      readonly attribute HighlightsRegister highlights;
    };

    [Exposed=Window]
    interface HighlightsRegister {
      setlike<Highlight>;
      HighlightsRegister add(Highlight value);
    };

## Issues Index

should negative numbers mean stacking below the built-in highlight pseudo-elements? <https://github.com/w3c/csswg-drafts/issues/4593> ↵
Should priority be an (unsigned) integer instead? That would make comparisons more reliable, but would likely lead to numbering reminiscent of BASIC line numbers. <https://github.com/w3c/csswg-drafts/issues/4592> ↵
Should we drop priority by numbers entirely, and replace it with some other ordering mechanism? Experience with BASIC line number or z-index does not give much confidence that ordering by number is a good idea. Is placing in an ordered data-structure better? Should authors be able to express a desired to be placed above/below other named highlights, and let the UA figure it out? <https://github.com/w3c/csswg-drafts/issues/4591> ↵
Should the built-in highlight pseudo-elements be exposed as well, so that they too can be reordered, and so that they can be interleaved with custom ones freely? <https://github.com/w3c/csswg-drafts/issues/4594> ↵
How should we specify the timing (and synchronicity) of this reevaluation? <https://github.com/w3c/csswg-drafts/issues/4596> ↵
As far as I am aware, prior uses of `StaticRange`s were for ranges created by the User Agent and passed to the author. Here, it’s the other way around, which raises (for the first time?) the question of invalidation of static ranges. Can the above work? Is it Fast enough that it’s worth distinguishing static and live ranges? Would some alternative handling be better? <https://github.com/w3c/csswg-drafts/issues/4597> ↵
The interaction of `StaticRange`s in a custom highlight and [css-contain-2] seems problematic: on a fully contained element, you should expect that DOM changes to descendants of that element will not cause invalidation and restyling/repainting of elements outside the contained one. However, if a static range has a boundary point inside the contained subtree and another boundary point outside of it, and the DOM in the contained subtree is changed so that the boundary point inside no longer points to a valid node, the whole range should be ignored, which would affect painting outside the contained subtree. Is this a weakness of style containment, or of the invalidation logic above, or something else? <https://github.com/w3c/csswg-drafts/issues/4598> ↵
Section on Events TBD, based on https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/master/highlight/events-explainer.md ↵
should custom highlights have a dedicated event handling mechanism, or should that be added to pseudo-elements in general? ↵
Provide summary of Privacy and Security Considerations for this specification ↵
Acknowledge people (other than editors) who deserve credit for this. ↵
#custom-highlight Referenced in:

- 3.1. Creating Custom Highlights (2) (3) (4)
- 3.2. Registering Custom Highlights (2) (3) (4) (5)
- 4.1. The Custom Highlight Pseudo-element: ::highlight()
- 4.2.3. Painting (2) (3) (4)
- 4.2.4. Priority of Overlapping Highlights (2)
- 5.1. Repaints (2) (3)
- 5.2. Range Updating and Invalidation (2) (3) (4) (5)

#highlight Referenced in:

- 1. Introduction (2)
- 3.1. Creating Custom Highlights (2)
- 3.2. Registering Custom Highlights (2)

#custom-highlight-name Referenced in:

- 4.1. The Custom Highlight Pseudo-element: ::highlight()

#dom-highlight-highlight-name-initialranges-name Referenced in:

- 3.1. Creating Custom Highlights (2)

#dom-highlight-highlight-name-initialranges-initialranges Referenced in:

- 3.1. Creating Custom Highlights

#dom-highlight-priority Referenced in:

- 3.1. Creating Custom Highlights (2)
- 4.2.4. Priority of Overlapping Highlights
- 5.1. Repaints

#dom-highlight-name Referenced in:

- 3.1. Creating Custom Highlights (2)
- 3.2. Registering Custom Highlights (2)

#dom-highlight-highlight Referenced in:

- 3.1. Creating Custom Highlights

#highlights-register Referenced in:

- 3.2. Registering Custom Highlights (2) (3)
- 4.2.4. Priority of Overlapping Highlights
- 5.1. Repaints
- 5.2. Range Updating and Invalidation

#registered Referenced in:

- 3.2. Registering Custom Highlights (2) (3) (4)
- 4.1. The Custom Highlight Pseudo-element: ::highlight()
- 4.2.4. Priority of Overlapping Highlights
- 5.1. Repaints

#dom-css-highlights Referenced in:

- 3.2. Registering Custom Highlights

#highlightsregister Referenced in:

- 1. Introduction
- 3.2. Registering Custom Highlights (2)

#dom-highlightsregister-add-value-value Referenced in:

- 3.2. Registering Custom Highlights (2)

#dom-highlightsregister-add Referenced in:

- 3.2. Registering Custom Highlights (2)

#selectordef-highlight-highlight-name Referenced in:

- 1. Introduction (2)
- 4.1. The Custom Highlight Pseudo-element: ::highlight()

#custom-highlight-pseudo-element Referenced in:

- 4.2.1. Applicable Properties
- 4.2.2. Cascading and Inheritance

#typedef-highlight-name Referenced in:

- 4.1. The Custom Highlight Pseudo-element: ::highlight() (2) (3)

#priority Referenced in:

- 4.2.3. Painting
- 4.2.4. Priority of Overlapping Highlights (2)