react-track
Avoid it if you can, but for a certain class of (mostly animation-related)
problems, you need to query the DOM. This library provides a way to track
DOM elements in a functional, declarative manner.
npm install react-track --save
Note: tweening, animation, and timeline-related stuff lives here: react-imation
<TrackDocument />
Used to track:
document.documentElementdocument.documentElement.getBoundingClientRect()
import {TrackDocument, Track} from 'react-track';
import {getDocumentRect,
getDocumentElement} from 'react-track/tracking-formulas';
// ...render:
<TrackDocument formulas={[getDocumentRect]}>
{rect =>
<div>
The height of documentElement is {rect.height}
</div>}
</TrackDocument>
<Track />
Use <Track /> to track any Component instance. For example,
track an <h2 />:
import {TrackDocument, Track} from 'react-track';
import {topTop} from 'react-track/tracking-formulas';
// ...render:
<TrackDocument formulas={[topTop]}>
{topTop =>
<Track component="h2" formulas={[topTop]}>
{(H2,posTopTop) =>
<H2>My top is {posTopTop}px from the viewport's top.</H2>
}</Track>
}</TrackDocument>
or track your AwesomeComponent
// ...render:
<TrackDocument formulas={[topTop]}>
{topTop =>
<Track component={AwesomeComponent} formulas={[topTop]}>
{(AwesomeComponentTracked,posTopTop) =>
<AwesomeComponentTracked>
My top is {posTopTop}px from the viewport's top.
</AwesomeComponentTracked>
}</Track>
}</TrackDocument>
It's important to note that AwesomeComponent must be stateful in this example.
At the time of writing react-track does not support stateless functional
components (SFCs) due to its reliance on the ref attribute, which such
components do not provide. In order to track an SFC, wrap it in a
TrackedDiv.
Note that in the code above, there are two different
scopes with a topTop variable. One scope is nested
inside of the other. The topTop variable of the inner
scope is the result of calling the topTop of the
outer scope which returns type function. Here is the definition of the topTop
function of the outer scope:
export const topTop = containerRect => rect =>
~~(rect.top - containerRect.top);
In the outer scope, the <TrackDocument /> component supplies
the containerRect argument, which comes from
document.documentElement.getClientBoundingRect().
In the inner scope, the <Track /> component supplies the rect argument
which comes from awesomeDOMElement.getClientBoundingRect().
trackedRef
<Track /> supports an optional trackedRef prop which
is type Function, and works the same way as the functional form of
React's built-in ref prop.
<TrackedDiv />
It's pretty common to need to track a div, so there's
TrackedDiv component which is a slightly simpler version of Track:
import {TrackDocument, TrackedDiv} from 'react-track';
import {topBottom} from 'react-track/tracking-formulas';
// ...render:
<TrackDocument formulas={[topBottom]}>
{topBottom =>
<TrackedDiv formulas={[topBottom]}>
{(posTopBottom) =>
<b>My top is {posTopBottom}px from the viewport's bottom</b>
}</TrackedDiv>
}</TrackDocument>
tracking-formulas.js
The tracking components
explained above all accept a formulas prop which expects an array
of formula functions. When a tracking component renders, it passes
the same arguments to all of the formulas and the results
are passed as arguments into the function which you should
supply to the children prop of the tracking component.
The signature for all formula functions which are passed as an
array into the formulas prop is:
trackingFormula(rect, element) {
// return any type
}
Of course, it's common to only utilize the first
or second argument.
Notice that all of the following are valid formulas
that only utilize a single argument:
const getDocumentRect = documentRect => documentRect;
const getDocumentElement = (_,documentElement) => documentElement;
const calculateScrollY = ({top}) => -top;
Here's a valid formula which returns a valid formula:
const centerCenter = (containerRect, container) => rect =>
~~(rect.top + rect.height / 2 - containerRect.top - container.clientHeight / 2);
When a formula returns a formula, we are calculating something that
relies on tracking two different elements. In this case, centerCenter
calculates the distance from the vertical center of some element to
the vertical center of some container element. The container element could
be document.documentElement if you utilize TrackDocument,
or it could be any other DOM element if you utilize Track or TrackedDiv.
Creating custom formulas is relatively easy.
Check out tracking-formulas.js
for inspiration.
Contributing
Publishing to NPM
-
First make sure to bump the version number in
package.jsonin accordance with semantic versioning practices. If you think a major version bump is warranted, go for it!# preparation npm run build-npm # actually publish to npm npm run publish -
Create a git tag and publish it
git tag vVERSION.NUMBER.WHATEVER git push origin vVERSION.NUMBER.WHATEVER