# @n8tb1t/use-scroll-position
> React hook to calculate scroll position
Latest version **4.0.0** (published 2025-09-23) · MIT license · 0 weekly downloads
## Install
```sh
npm install @n8tb1t/use-scroll-position
pnpm add @n8tb1t/use-scroll-position
yarn add @n8tb1t/use-scroll-position
bun add @n8tb1t/use-scroll-position
```
## Health
**Score 35/100 (D)** — status: maintenance-mode.
Positive: has types; esm support; no vulnerabilities.
Warnings: low downloads.
Negative: stale; low maintenance score.
## Facts
| | |
|---|---|
| Version | 4.0.0 |
| Published | 2025-09-23 |
| First published | 2019-06-21 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 39.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | n8tb1t |
| Maintainers | n8tb1t |
| Keywords | react, hooks, react-hooks, scroll, scroll-position, use-scroll-position, useScrollPosition |
## Links
- npm: https://www.npmjs.com/package/@n8tb1t/use-scroll-position
- Repository: https://github.com/n8tb1t/use-scroll-position
- Homepage: https://github.com/n8tb1t/use-scroll-position#readme
- Issues: https://github.com/n8tb1t/use-scroll-position/issues
- npm.io page: https://npm.io/package/@n8tb1t/use-scroll-position
## Alternatives
- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads
## Recent versions
- 4.0.0 (latest) — 2025-09-23
- 1.0.18 (1.0.18) — 2019-06-23
- 1.0.17 (1.0.17) — 2019-06-23
- 1.0.12 ($npm_package_version) — 2019-06-23
- 3.0.1 — 2025-09-11
- 3.0.0 — 2025-09-11
- 2.0.3 — 2020-10-17
- 2.0.2 — 2020-10-17
- 2.0.1 — 2020-10-17
- 1.0.47 — 2020-09-15
- 1.0.46 — 2020-09-13
- 1.0.45 — 2020-09-13
- 1.0.44 — 2020-09-13
- 1.0.43 — 2019-11-20
- 1.0.42 — 2019-11-08
- … 33 more at https://npm.io/package/@n8tb1t/use-scroll-position/versions
## README
# use-scroll-position
[](https://www.npmjs.com/package/@n8tb1t/use-scroll-position)
[](https://www.npmjs.com/package/@n8tb1t/use-scroll-position)
[](https://github.com/n8tb1t/use-scroll-position/blob/master/LICENSE)
`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](https://github.com/n8tb1t/use-scroll-position/blob/develop/README-LEGACY.md).
---
## ⚡️ Quickstart
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)
})
```
---
## 📖 Documentation
👉 [Full Docs Site](https://n8tb1t.github.io/use-scroll-position)
- [useWindowScrollPosition](https://n8tb1t.github.io/use-scroll-position/use-window-scroll-position) – track global window scroll or specific element position.
- [useBodyScrollPosition](https://n8tb1t.github.io/use-scroll-position/use-body-scroll-position) – similar to window scroll, with a different detection method.
- [useOverflowScrollPosition](https://n8tb1t.github.io/use-scroll-position/use-overflow-scroll-position) – 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**:
```bash
npm install @n8tb1t/use-scroll-position
```
Using **PNPM**:
```bash
pnpm add @n8tb1t/use-scroll-position
```
---
## 🚀 Usage
### Track window 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)
})
```
---
### Track element position in the viewport (window)
```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
```
---
### Track scroll position in an overflow container
```tsx
const [setRootRef] = useOverflowScrollPosition(({ prevPos, currPos, top, bottom }) => {
console.log(prevPos, currPos, top, bottom) // root container scroll
})
return (
)
```
---
### Track element scroll position inside an overflow container
```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 `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](https://github.com/n8tb1t/use-scroll-position/blob/develop/CONTRIBUTING.md).
---
---
_Source: https://npm.io/package/@n8tb1t/use-scroll-position · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._