react-atom-trigger — Simple “react-waypoint” Alternative

A lot of developers including me solved the problem of executing code when some element “scrolls into view” (or, in other words, when you scroll to an element) with help of react-waypoint. In the end of 2021 something clicked in my head and I decided to do my own take on React Waypoint alternative, written in Typescript and having some cool features…

React Atom Trigger

react-atom-trigger is a library that exposes the main AtomTrigger component and some utility hooks.

When AtomTrigger scrolls into (or out of) view, based on provided options, it executes provided callback.

Here is a quick example showing how animations are triggered by provided callback when AtomTrigger enters or leaves the view:

Please scroll. Not bad, huh?

The props of AtomTrigger:

interface IAtomTriggerProps {
  scrollEvent: ScrollEvent;
  dimensions: Dimensions | null;
  behavior?: 'default' | 'enter' | 'leave';
  callback: () => unknown;
  getDebugInfo?: (data: DebugInfo) => void;
  triggerOnce?: boolean;
  className?: string;
  offset?: [number, number, number, number];
}

In order to “work” AtomTrigger needs callback, dimensions and simple scroll event data provided.

Callback

callback: () => unknown;

The function to be executed when AtomTrigger enters or leaves some view or container.

Dimensions

Dimensions of the main view or “container” (window in many cases).

type Dimensions = {
  width: number;
  height: number;
}; 

So if you have some logic of calculating container size and container resize handling, just provide needed data to AtomTrigger.

Scroll Event

To trigger callback execution AtomTrigger also needs simple scroll event data provided.

type ScrollEvent = { 
    scrollX: number; 
    scrollY: number 
};

So, if you already have some scroll event listener, just provide it to AtomTrigger.

Optional props

With optional props you can customise the behavior of AtomTrigger.

behavior

behavior?: 'default' | 'enter' | 'leave';

default: callback will be fired when AtomTrigger enters and leaves the “container”.

enter: callback will be fired only when AtomTrigger enters the “container”.

leave: callback will be fired only when AtomTrigger leaves the “container”.

triggerOnce

triggerOnce?: boolean;

Callback will be fired only once.

className

className?: string;

You can provide styling to AtomTrigger element for debugging or some other purpose.

Offset

offset?: [number, number, number, number];

Offset parameter numbers represent number of pixels to offset. This might be handy if you have some sticky/fixed elements on your page. The order of numbers resembles CSS padding/margin: top, right, bottom, left.

Better to see for yourself in this example:

Please scroll and look at the console

Utility hooks

For someone who wants everything out-of-the-box, useWindowDimensions, useWindowScroll and useContainerScroll hooks are also available for import. As seen in code and typings, they handle container resize and have some configuration options.

Examples

It is sometimes better to tweak and see for yourself: examples on CodeSandbox.

Useful links

react-atom-trigger on GitHub

react-atom-trigger on npm

PS

I thank react-waypoint authors for the inspiration.