@n8tb1t/use-scroll-position

use-scroll-position

use-scroll-position is a lightweight, tree-shakable React hook library for detecting and tracking scroll position — either of the window or a specific element. Designed for performance-sensitive use cases.

⚡️ Version 4.0.0 is a complete rewrite of the library.
For older versions, see the legacy docs.

⚡️ Quickstart

Track the global window scroll position in just a few lines:

import { useWindowScrollPosition } from '@n8tb1t/use-scroll-position'

useWindowScrollPosition(({ currPos }) => {
  console.log('Current scroll position:', currPos.y)
})

📖 Documentation

👉 Full Docs Site

• useWindowScrollPosition – track global window scroll or specific element position.
• useBodyScrollPosition – similar to window scroll, with a different detection method.
• useOverflowScrollPosition – track scroll inside an overflow container (supports root + child target refs).

✨ Features

• ✅ React 19 support
• ✅ SSR-ready
• ✅ LLM-friendly docs
• ✅ Native TypeScript

📦 Installation

Using NPM:

npm install @n8tb1t/use-scroll-position

Using PNPM:

pnpm add @n8tb1t/use-scroll-position

🚀 Usage

Track window scroll position

useWindowScrollPosition(({ prevPos, currPos, top, bottom }) => {
  console.log(prevPos, currPos, top, bottom)
})

useBodyScrollPosition(({ prevPos, currPos, top, bottom }) => {
  console.log(prevPos, currPos, top, bottom)
})

Track element position in the viewport (window)

const setElementRef = useWindowScrollPosition(({ prevPos, currPos, top, bottom }) => {
  console.log(prevPos, currPos, top, bottom)
})

return <div ref={setElementRef} />

const setElementRef = useBodyScrollPosition(({ prevPos, currPos, top, bottom }) => {
  console.log(prevPos, currPos, top, bottom)
})

return <div ref={setElementRef} />

Track scroll position in an overflow container

const [setRootRef] = useOverflowScrollPosition(({ prevPos, currPos, top, bottom }) => {
  console.log(prevPos, currPos, top, bottom) // root container scroll
})

return (
  <div ref={setRootRef} style={{ height: '100px', width: '300px', overflow: 'auto' }} />
)

Track element scroll position inside an overflow container

const [setRootRef, setTargetRef] = useOverflowScrollPosition(({ prevPos, currPos, top, bottom }) => {
  console.log(prevPos, currPos, top, bottom) // target element scroll
})

return (
  <div ref={setRootRef} style={{ height: '100px', width: '300px', overflow: 'auto' }}>
    <div ref={setTargetRef} />
  </div>
)

💡 Use Cases

Here are some common ways developers use use-scroll-position:

• Sticky Headers & Navbars – hide, reveal, or shrink navigation bars depending on scroll direction.
• Infinite Scrolling – detect when the user reaches the bottom of a container or the window to load more data.
• Scroll-Based Animations – trigger animations or transitions as elements enter the viewport.
• Active Section Highlighting – update navigation menus (scrollspy effect) as the user scrolls through sections.
• Custom Parallax Effects – adjust element positions or backgrounds smoothly based on scroll position.
• Performance Monitoring – track scroll behavior for analytics or user experience optimization.

🤝 Contributing

See the Contributing Rules.