React hook to calculate scroll position
npm install @n8tb1t/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.
---
Track the global window scroll position in just a few lines:
``tsx
import { useWindowScrollPosition } from '@n8tb1t/use-scroll-position'
useWindowScrollPosition(({ currPos }) => {
console.log('Current scroll position:', currPos.y)
})
`
---
- 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).
---
- ✅ React 19 support
- ✅ SSR-ready
- ✅ LLM-friendly docs
- ✅ Native TypeScript
---
Using NPM:
`bash`
npm install @n8tb1t/use-scroll-position
Using PNPM:
`bash`
pnpm add @n8tb1t/use-scroll-position
---
`tsx`
useWindowScrollPosition(({ prevPos, currPos, top, bottom }) => {
console.log(prevPos, currPos, top, bottom)
})
`tsx`
useBodyScrollPosition(({ prevPos, currPos, top, bottom }) => {
console.log(prevPos, currPos, top, bottom)
})
---
`tsx
const setElementRef = useWindowScrollPosition(({ prevPos, currPos, top, bottom }) => {
console.log(prevPos, currPos, top, bottom)
})
return
tsx
const setElementRef = useBodyScrollPosition(({ prevPos, currPos, top, bottom }) => {
console.log(prevPos, currPos, top, bottom)
})return
`---
$3
tsx
const [setRootRef] = useOverflowScrollPosition(({ prevPos, currPos, top, bottom }) => {
console.log(prevPos, currPos, top, bottom) // root container scroll
})return (
)
`---
$3
tsx
const [setRootRef, setTargetRef] = useOverflowScrollPosition(({ prevPos, currPos, top, bottom }) => {
console.log(prevPos, currPos, top, bottom) // target element scroll
})return (
)
`---
💡 Use Cases
Here are some common ways developers use
- 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.
---
See the Contributing Rules.
---