react-track-elements
Keep track of values provided by child elements deeply nested in a React component tree.
What?
This is a utility library for reactively keeping track of values provided by elements at arbitrary nesting levels in a React component tree.
Why?
This is useful for situations where you want to send data only available in child components up to a common ancestor. The primary use case is rendering an overlay based on properties of rendered DOM nodes.
How?
react-track-elements
provides a useReporter
hook that's used by components to provide a value to keep track of along with a unique identifier for each component. When the component mounts, the value gets reported up to a common parent (Tracker
) element that keeps this value alongside the id
. Whenever the value changes, the updated value gets reported again, and finally when the reporting component unmounts, the value along with the component identifier will be removed. The list of tracked values, identifier pairs can be accessed using the useReportedValues()
hook.
Usage
import Tracker useReporter useReportedValues from 'react-track-elements' // this component will report it's message to the Tracker { return <div> reporting propsmessage</div>} // This component consumes all reported values through the `useReportedValues()` hook { const reportedValues = return <div> reportedValues </div> } { return <Tracker> <SomeComponentWithReporters /> <ListReportedValues /> </Tracker> }
Reporting DOM elements
Sometimes it can useful to keep track of actual DOM elements in a component tree. In order to report these, an initializer function that returns the value to be reported can be provided to useReporter()
instead of an actual value. This initializer will be run after the component has been mounted, so you can safely access the element from there.
// this component will report it's element { return <div => reporting this element</div>} { const reportedElements = return <div> reportedElements </div> } { return <Tracker> <div> <ElementReporter /> <div> <ElementReporter /> </div> </div> <ListReportedValues /> </Tracker> }
Gotcha: Render cascading and infinite render loops
Since the useReportedValues()
-hook triggers a re-render whenever it receives an updated value from a reporter this can easily lead to infinite render loops.In development, you will see React warn about this with a message saying something like Error: Maximum update depth exceeded
There's a couple of ways to prevent this from happening:
- Provide am equality function to
useReporter()
- Don't use the
useReporter()
hook in a subtree of a component that is using theuseReportedValues()
hook.
useReporter()
1. Provide an equality function to By providing an equality function to useReporter()
you can prevent identical values from being reported and causing a re-renders.
If you don't provide an equality function, useReporter()
will default to referential equality using Object.is.
Keep in mind that every time a new unique value gets reported, a re-render is triggered in every component using the useReportedValues()
hook, so it's always a good thing to provide an equality function.
{ // Since useReporter will be called with a different object every time, // we provide a custom equality check to avoid unneccessary renders in // the component(s) that consumes the reported values return <div> reporting propsmessage</div>}
useReportedValues()
hook.
2. Don't consume reported values in a component with children using the The reported values can only be accessed within a child component of the <Tracker>
.
// This component consumes all reported values through the `useReportedValues()` hook { // <- Avoid doing this! const reportedValues = return <div> reportedValues </div> } { return <Tracker> /* All the reporting components are rendered in here */ <SomeComponentWithReporters /> /* This is where we read the reported values */ <ListReportedValues /> </Tracker> }
API
-
Tracker
- A wrapper component for a subtree which values can be reported in. -
useReporter(id: string, value: T | (()=> T)): void
- A React hook for reporting values from a component. -
useReportedValues(): T
- A React hook for consuming all the reported values from the tracker. -
function createScope<T>()
This creates a new isolated Tracker scope with aTracker
component, auseReporter()
- hook and auseReportedValues()
-hook with the API defined above.
Tracker scope
In order to separate concerns its possible to have several scoped trackers reporting values in isolation.
To create an isolated scope, the createScope
function can be used:
import createScope from 'react-track-elements' const Tracker useReporter useReportedValues = //…
License
MIT