react-scroll-detect

Tells you which section of the page the reader is currently looking at.

Wrap a stack of sections, and onChange fires with the index of whichever one is crossing an imaginary line in the viewport. Useful for highlighting the active item in a sticky nav, firing analytics as a long article is read, or driving a scroll-linked animation.

No dependencies, no configuration, about 1 kB gzipped.

Codesandbox demo

Install

npm install react-scroll-detect

React 16.8 or newer is required (the components are built on hooks). React is a peer dependency, so it uses whichever copy your app already has.

Usage

import { useState } from 'react';
import ReactScrollDetect, { DetectSection } from 'react-scroll-detect';

function Article() {
  const [active, setActive] = useState(0);

  return (
    <>
      <nav>
        {['Intro', 'Details', 'Summary'].map((label, i) => (
          <a key={label} className={i === active ? 'active' : ''}>{label}</a>
        ))}
      </nav>

      <ReactScrollDetect onChange={setActive}>
        <DetectSection><Intro /></DetectSection>
        <DetectSection><Details /></DetectSection>
        <DetectSection><Summary /></DetectSection>
      </ReactScrollDetect>
    </>
  );
}

onChange receives the zero-based index of the active section, counted in document order. It fires only when the active section actually changes, so it is safe to pass straight to a useState setter.

How detection works

triggerPoint puts a horizontal line across the viewport. The active section is the one that line is currently sitting inside — formally, the last section whose top edge has passed the line.

The three settings can report three different sections from the very same scroll position:

        ┌─────────────────────────┐ ◀── triggerPoint='top'      onChange(0)
        │        section 0        │
        ├─────────────────────────┤
        │                         │
        │                         │
        │        section 1        │ ◀── triggerPoint='center'   onChange(1)
        │                         │
        ├─────────────────────────┤
        │        section 2        │
        └─────────────────────────┘ ◀── triggerPoint='bottom'   onChange(2)

Pick 'top' if a section should become active as soon as it reaches the top of the screen, 'bottom' if it should activate the moment it first appears, and 'center' (the default) for the usual reading-position behaviour.

Before the first section has reached the line — at the very top of a page that starts with a tall header — index 0 is reported.

Positions are measured live on every scroll, so sections that grow, shrink, reflow on a resize, or arrive late (images, lazily loaded content) are all handled without any invalidation step on your side.

Scrolling to a section

Pass index to drive the scroll position yourself. Whenever the value changes, that section is smooth-scrolled into view:

<ReactScrollDetect index={target} offset={80} onChange={setActive}>

Use offset to leave room for a fixed header — an offset of 80 stops 80px short of the section's top edge.

index is uncontrolled: setting it scrolls once, and the reader is then free to scroll away. Leave the prop off entirely if you only want detection, and nothing will touch the scroll position.

API