diff --git a/files/en-us/web/api/highlightregistry/highlightsfrompoint/index.md b/files/en-us/web/api/highlightregistry/highlightsfrompoint/index.md new file mode 100644 index 000000000000000..ab66bc254571bd8 --- /dev/null +++ b/files/en-us/web/api/highlightregistry/highlightsfrompoint/index.md @@ -0,0 +1,204 @@ +--- +title: "HighlightRegistry: highlightsFromPoint() method" +short-title: highlightsFromPoint() +slug: Web/API/HighlightRegistry/highlightsFromPoint +page-type: web-api-instance-method +browser-compat: api.HighlightRegistry.highlightsFromPoint +--- + +{{APIRef("CSS Custom Highlight API")}} + +The **`highlightsFromPoint()`** method of the {{domxref("HighlightRegistry")}} interface returns an array of objects representing the custom highlights applied at a specific point within the viewport. + +## Syntax + +```js-nolint +highlightsFromPoint(x, y) +highlightsFromPoint(x, y, options) +``` + +### Parameters + +- `x` + - : The x-coordinate of the point within the viewport from which to return custom highlight information. +- `y` + - : The y-coordinate of the point within the viewport from which to return custom highlight information. +- `options` {{optional_inline}} + - : An object containing options, which can include: + - `shadowRoots` + - : An array of {{domxref("ShadowRoot")}} objects. Custom highlights that exist at the specified point inside shadow roots in the array will also be included in the return value, in addition to those present in the light DOM. By default, highlights inside shadow roots are not returned. + +### Return value + +An array of `HighlightHitResult` objects representing the custom highlights applied at the point in the viewport specified by the `x` and `y` parameters. + +Each `HighlightHitResult` object contains the following properties: + +- `highlight` + - : A {{domxref("Highlight")}} object representing the applied custom highlight. +- `ranges` + - : An array of {{domxref("AbstractRange")}} objects representing the ranges to which the custom highlight is applied. + +If no custom highlights are applied at the specified point, or the specified point is outside the viewport, the method returns an empty array. + +## Examples + +### Output custom highlights applied at the mouse pointer position + +In this example, you can apply custom highlights to a paragraph of text. These custom highlights can be overlapping. When the user double-clicks the paragraph, we use the `highlightsFromPoint()` method to return the content of any custom highlights located at the mouse pointer coordinates of the double-click. + +#### HTML + +The markup includes a {{htmlelement("p")}} element containing text to which you can apply custom highlights, and a {{htmlelement("section")}} element into which we will output the highlighted text fragments. + +```html live-sample___highlights-from-point-example +
+ When you select a section of text then press "h" on the keyboard, the text you + selected will be given a custom highlight. Multiple highlights will be colored + yellow, red, and blue, in that order. When you double-click on a highlighted + section of text, that section will be outputted at the bottom of the UI. If + multiple highlights overlap the section, you'll see multiple text sections + outputted. +
+` element and its contained text node. We then create a variable called `highlightCount`, initially set to `1`, which will be used to specify which custom highlight to apply later on.
+
+```js live-sample___highlights-from-point-example
+const pElem = document.querySelector(".highlightable-text");
+const textNode = pElem.firstChild;
+let highlightCount = 1;
+```
+
+Next, we define a [`keydown`](/en-US/docs/Web/API/Element/keydown_event) event handler that applies a custom highlight to any selected text if h is pressed on the keyboard. Inside, we start by grabbing the selected text using {{domxref("Window.getSelection()")}} and converting it to a {{domxref("Range")}} using {{domxref("Selection.getRangeAt()")}}.
+
+We check that the `selectedRange` object's [`startContainer`](/en-US/docs/Web/API/Range/startContainer) and [`endContainer`](/en-US/docs/Web/API/Range/endContainer) are both equal to the paragraph `textNode`, to make sure we don't allow any cross-container highlights. If so, we set the custom `highlightName` we want to apply to the `selectedRange` using `highlight${highlightCount++}`. Since we are incrementing `highlightCount`, we add in a check — when it reaches `4`, we set it back to `1`. This has the effect of cycling through the available highlights in order as they are set.
+
+Finally for the `keydown` event handler, we create a new `highlight` object using the {{domxref("Highlight.Highlight", "Highlight()")}} constructor, passing it the `selectedRange` we created earlier. We then apply the chosen custom highlight referenced in `highlightName` to `highlight` using the {{domxref("HighlightRegistry.set()")}} method.
+
+```js live-sample___highlights-from-point-example
+window.addEventListener("keydown", (event) => {
+ if (event.key === "h") {
+ const selection = window.getSelection();
+ const selectedRange = selection.getRangeAt(0);
+ if (
+ selectedRange.startContainer === textNode &&
+ selectedRange.endContainer === textNode
+ ) {
+ const highlightName = `highlight${highlightCount++}`;
+ if (highlightCount === 4) {
+ highlightCount = 1;
+ }
+ const highlight = new Highlight(selectedRange);
+ CSS.highlights.set(highlightName, highlight);
+ }
+ }
+});
+```
+
+##### Returning custom highlights from a point
+
+Now that we have the ability to create and apply custom highlights, we can use the `highlightsFromPoint()` method to return the custom highlights applied at a specific point.
+
+We grab a reference to our `