|
| 1 | +--- |
| 2 | +title: CSS custom highlight API |
| 3 | +slug: Web/CSS/CSS_custom_highlight_API |
| 4 | +page-type: css-module |
| 5 | +spec-urls: https://drafts.csswg.org/css-highlight-api-1/ |
| 6 | +sidebar: cssref |
| 7 | +--- |
| 8 | + |
| 9 | +The **CSS custom highlight API** module provides a programmatic way to target specific ranges of text defined by range objects, without affecting the underlying DOM structure. The range objects can then be selected via `::highlight()` pseudo-elements, and have highlight styles added and removed. The features of this module can create highlight effects similar to how text editors highlight spelling or grammar errors, and code editors highlight syntax errors. |
| 10 | + |
| 11 | +The CSS Custom Highlight API extends the concept of other highlight pseudo-elements such as {{cssxref('::selection')}}, {{cssxref('::spelling-error')}}, {{cssxref('::grammar-error')}}, and {{cssxref('::target-text')}} by providing a way to create arbitrary text ranges (defined as {{domxref('Range')}} objects in JavaScript) and style them via CSS, rather than being limited to browser-defined ranges. |
| 12 | + |
| 13 | +## Custom highlight API in action |
| 14 | + |
| 15 | +To enable styling text ranges on a webpage using the CSS Custom Highlight API, you create a {{domxref("Range")}} object, then a {{domxref("Highlight")}} object for the range. After registering the highlight using the {{domxref("HighlightRegistry.set()")}} method, you can then select the range using the {{cssxref("::highlight", "::highlight()")}} pseudo-element. The name defined in the `set()` method is used as the parameter of the `::highlight()` pseudo-element selector to select that range.The range selected by the `::highlight()` pseudo-element can be styled using a [limited number of properties](/en-US/docs/Web/CSS/::highlight#allowable_properties). |
| 16 | + |
| 17 | +```html-nolint hidden |
| 18 | +<h1>Directions</h1> |
| 19 | +<h2>Lincoln Memorial to Martin Luther King, Jr. Memorial</h2> |
| 20 | +<ol><li>Head south on Lincoln Memorial Circle</li |
| 21 | + ><li>Turn right toward Independence Ave</li |
| 22 | + ><li>Turn left onto Independence Ave</li |
| 23 | + ><li>Turn right onto West Basin Dr</li |
| 24 | + ><li>Look up when you reach 64 Independence Ave!</li> |
| 25 | +</ol> |
| 26 | +<hr /> |
| 27 | +<label |
| 28 | + >Number of steps completed: |
| 29 | + <input type="number" min="0" max="5" value="0" id="currentStep" /> |
| 30 | +</label> |
| 31 | +``` |
| 32 | + |
| 33 | +This example uses the {{cssxref("text-decoration")}} property to strike throgh the `steps` highlight range defined by our JavaScript: |
| 34 | + |
| 35 | +```css |
| 36 | +::highlight(steps) { |
| 37 | + text-decoration: line-through; |
| 38 | + color: blue; |
| 39 | +} |
| 40 | +``` |
| 41 | + |
| 42 | +We create a `Range` with a start and end node (which is the same node in this case). We then set this range as the `Highlight` using the `set()` method of the CSS `HighlightRegistry` interface. |
| 43 | + |
| 44 | +```js |
| 45 | +const rangeToHighlight = new Range(); |
| 46 | +const list = document.querySelector("ol"); |
| 47 | +rangeToHighlight.setStart(list, 0); |
| 48 | +rangeToHighlight.setEnd(list, 0); |
| 49 | + |
| 50 | +CSS.highlights.set("steps", new Highlight(rangeToHighlight)); |
| 51 | +``` |
| 52 | + |
| 53 | +An event listener updates the end of the highlighted range when the number of completed steps changes: |
| 54 | + |
| 55 | +```js |
| 56 | +const currentPositionSlider = document.querySelector("input"); |
| 57 | +currentPositionSlider.addEventListener("change", (e) => { |
| 58 | + rangeToHighlight.setEnd(list, e.target.value); |
| 59 | +}); |
| 60 | +``` |
| 61 | + |
| 62 | +{{ EmbedLiveSample('Custom highlight API in action', 700, 300) }} |
| 63 | + |
| 64 | +## Reference |
| 65 | + |
| 66 | +### Pseudo-elements |
| 67 | + |
| 68 | +- {{CSSXref("::highlight()")}} |
| 69 | + |
| 70 | +### Interfaces |
| 71 | + |
| 72 | +- {{domxref("Highlight")}} |
| 73 | +- {{domxref("HighlightRegistry")}} |
| 74 | + |
| 75 | +### Interface extensions |
| 76 | + |
| 77 | +This module adds properties and methods to interfaces defined in other specifications. |
| 78 | + |
| 79 | +- {{domxref("CSS")}} |
| 80 | + - {{domxref("CSS.highlights")}} |
| 81 | + |
| 82 | +## Guides |
| 83 | + |
| 84 | +- [CSS custom highlight API](/en-US/docs/Web/API/CSS_Custom_Highlight_API#concepts_and_usage) |
| 85 | + - : The concepts and usage of the CSS custom highlight API, including creating `Range` and `Highlight` objects, registering the highlights using the `HighlightRegistry`, and styling the highlights using the `::highlight()` pseudo-element. |
| 86 | + |
| 87 | +## Related concepts |
| 88 | + |
| 89 | +- {{CSSXref("::grammar-error")}} |
| 90 | +- {{CSSXref("::selection")}} |
| 91 | +- {{CSSXref("::spelling-error")}} |
| 92 | +- {{CSSXref("::target-text")}} |
| 93 | +- {{domxref("Range")}} Interface and {{domxref("Range.range", "Range()")}} constructor |
| 94 | +- [Text fragments](/en-US/docs/Web/URI/Reference/Fragment/Text_fragments) |
| 95 | +- {{domxref("FragmentDirective")}} Interface |
| 96 | + |
| 97 | +## Specifications |
| 98 | + |
| 99 | +{{Specifications}} |
| 100 | + |
| 101 | +## See also |
| 102 | + |
| 103 | +- [CSS pseudo-element module](/en-US/docs/Web/CSS/CSS_pseudo-elements) |
| 104 | +- [CSS Object Model (CSSOM)](/en-US/docs/Web/API/CSS_Object_Model) APIs |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments