react-use-scroll-sync

React hook for synchronizing scroll position across multiple scrollable elements.

Installation

Requires react >= 18.

npm install react-use-scroll-sync

or

yarn add react-use-scroll-sync

Usage

import { useMemo, useRef } from "react"
import { useScrollSync } from "react-use-scroll-sync"

export function Example() {
  const leftRef = useRef<HTMLDivElement>(null)
  const rightRef = useRef<HTMLDivElement>(null)
  const refs = useMemo(() => [leftRef, rightRef], [])

  useScrollSync(refs, {
    horizontal: true,
    vertical: true,
    proportional: true,
    throttleWaitTime: 100,
  })

  return (
    <>
      <div ref={leftRef} style={{ overflow: "auto", width: 300, height: 300 }}>
        <div style={{ width: 600, height: 800 }}>Left content</div>
      </div>

      <div ref={rightRef} style={{ overflow: "auto", width: 300, height: 300 }}>
        <div style={{ width: 900, height: 1200 }}>Right content</div>
      </div>
    </>
  )
}

Options

| Option | Type | Default | Description | | --- | --- | --- | --- | | horizontal | boolean | true | Sync horizontal scrolling. | | vertical | boolean | true | Sync vertical scrolling. | | proportional | boolean | true | Map by scroll ratio instead of copying the raw offset. | | throttleWaitTime | number | 100 | Delay in milliseconds before a sync is flushed. |

Notes

• Pass at least two refs.
• Keep the refs array stable between renders, for example with useMemo.
• When an element has no scrollable overflow on an axis, the hook keeps the synced position at 0 for that axis.

Development

yarn bootstrap
yarn verify
yarn demo:dev

Useful root scripts:

• yarn build builds the library into dist/
• yarn test runs the Vitest suite
• yarn verify runs lint, tests, library build and demo build
• yarn demo:dev starts the Vite demo
• yarn demo:build creates a production build of the demo
• yarn demo:preview previews the built demo locally

Demo

The demo app lives in example/ and imports the local library source through a Vite alias, so it uses the same React instance as the app.

License

MIT