@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.