@ppasmik/react-scroll-trigger

A modern, TypeScript-based React component for monitoring scroll events and triggering callbacks when elements enter, exit, or progress through the viewport. This is a rewritten and modernized version of the original react-scroll-trigger package.

Each callback includes progress and velocity parameters, enabling precise control over animations and transitions based on scroll position and speed.

Installation

npm install @ppasmik/react-scroll-trigger

or via Yarn:

yarn add @ppasmik/react-scroll-trigger

Usage

import ScrollTrigger from '@ppasmik/react-scroll-trigger';

const MyComponent = () => {
  const [visible, setVisible] = useState(false);

  const onEnterViewport = () => {
    setVisible(true);
  };

  const onExitViewport = () => {
    setVisible(false);
  };

  return (
    <ScrollTrigger onEnter={onEnterViewport} onExit={onExitViewport}>
      <div className={`container ${visible ? 'container-animate' : ''}`} />
    </ScrollTrigger>
  );
};

The ScrollTrigger component is designed to be highly flexible. You can use it:

• As a standalone element without children

<ScrollTrigger onEnter={handleEnter} onExit={handleExit} />

• With children to receive events based on their dimensions

<ScrollTrigger onEnter={handleEnter} onProgress={handleProgress}>
  <section>
    <h1>Your content here</h1>
  </section>
</ScrollTrigger>

Common use cases include:

• Triggering animations when elements become visible
• Loading content dynamically based on scroll position
• Creating scroll-based transitions and effects
• Implementing infinite scroll functionality

Props

Prop	Type	Default	Description
component	ElementType	'div'	React component or HTML element to render as wrapper
containerRef	HTMLElement ⎮ string	document.documentElement	Scrolling container reference
throttleResize	number	100	Resize event throttle in ms
throttleScroll	number	100	Scroll event throttle in ms
triggerOnLoad	boolean	true	Whether to trigger onEnter on mount
onEnter	function	-	Called when element enters viewport ({progress, velocity}) => void
onExit	function	-	Called when element exits viewport ({progress, velocity}) => void
onProgress	function	-	Called during scroll ({progress, velocity}) => void

Standard React props (className, style, etc.) are also supported and will be passed to the wrapper element.

Technical Details

The component uses React hooks for efficient state management:

• useRef to track the DOM element position
• useState for viewport visibility and scroll tracking
• useEffect for handling scroll and resize events with proper cleanup

Visibility detection:

• Uses getBoundingClientRect() for accurate element position calculation
• Progress is calculated based on element's position relative to viewport:

  progress = 1 - elementRect.bottom / (viewportEnd + elementRect.height);

• Velocity is derived from scroll position changes over time
• All calculations are throttled (default 100ms) to optimize performance

The component is designed to work with both window-level scrolling and custom scroll containers (via containerRef prop), making it suitable for various layout scenarios.

License

MIT © [Peter Pasmik]

Acknowledgments

This package is a TypeScript rewrite of the original react-scroll-trigger package, modernized with current React practices and enhanced type safety.