React hook to asynchronously watch for DOM elements on the page using a selector
npm install use-element-watcher> React hook to asynchronously watch for DOM elements on the page using a selector
The inspiration for this hook was from creating a tour library that required managing references to multiple elements on the page either for highlighting or anchoring purposes. There are several problems this library solves beyond just calling document.querySelectorAll() to obtain references to the elements.
- Many times the target elements are not yet in the DOM when the tour component was first rendered. This requires watching for the target elements to appear and emitting a callback with the element object.
- Since tour libraries often need to modify CSS attributes on the element (such as z-index), existing values need to be tracked so they can be restored when the element is unwatched.
- A callback needs to be emitted when an element object is no longer watched so any required cleanup can occur.
``sh`
npm install --save use-element-watcher
This hook does not accept any input parameters.
This hook returns the following properties.
`
watchElement: (target: HTMLElement | string, callbacks: WatcherCallbacks) => void
unWatchAll: () => void
#### watchElement function
A function that accepts an element (via an object or selector string) and callbacks that will be emitted when the element is watched/unwatched on the page. It is recommended that you call this function on each render to maintain the element reference if it is re-created in the DOM.
#### unWatchAll function
A function that unwatches all elements registered with . The onUnwatch callback function will be emitted for each watched element when this is called. This function is also called when the component unmounts.
`typescript`
type WatcherCallbacks = {
onWatch?: (element: HTMLElement) => void
onUnwatch?: (element: HTMLElement, originalStyles: CSSStyleDeclaration) => void
}
The CSSStyleDeclaration type is builtin to Typescript and contains a shorthand object of all CSS properties.
The following example sets up a watcher that changes the background color of 3 elements as they are rendered in the DOM. Note that this example is somewhat contrived since you would normally be watching elements elsewhere in the DOM tree. It would be much better to use refs if you were actually building a component in this way :-)
`jsx
import React from "react";
import { useElementWatcher } from "use-element-watcher";
export default function App() {
const [step, setStep] = React.useState(1);
const { watchElement } = useElementWatcher();
watchElement(".first-step", {
onWatch: (element) => {
element.style.backgroundColor = "red";
}
});
watchElement(".second-step", {
onWatch: (element) => {
element.style.backgroundColor = "teal";
}
});
watchElement(".third-step", {
onWatch: (element) => {
element.style.backgroundColor = "green";
}
});
return (
style={{ marginTop: "20px" }}
>
Next step
Known limitations
- The library attempts to calculate a unique "id" for each watched element when using a selector so it knows when to cleanup as the DOM changes. Since there is no builtin concept of a unique element id in JS, it may not be 100% reliable. I would recommend adding HTML
Feel free to submit issues/PR's and I will do my best to respond.
This project is licensed under the terms of the MIT license.