{"id":13406590,"url":"https://github.com/n8tb1t/use-scroll-position","last_synced_at":"2026-01-09T22:53:42.002Z","repository":{"id":43181207,"uuid":"192907883","full_name":"n8tb1t/use-scroll-position","owner":"n8tb1t","description":"Use scroll position ReactJS hook done right","archived":false,"fork":false,"pushed_at":"2022-03-14T23:16:26.000Z","size":1378,"stargazers_count":624,"open_issues_count":14,"forks_count":65,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-05-17T17:02:38.863Z","etag":null,"topics":["hooks","react","react-hooks","scroll","scroll-position"],"latest_commit_sha":null,"homepage":"https://n8tb1t.github.io/use-scroll-position/navbar/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/n8tb1t.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-06-20T11:29:54.000Z","updated_at":"2024-05-14T18:53:04.000Z","dependencies_parsed_at":"2022-08-31T18:23:28.147Z","dependency_job_id":null,"html_url":"https://github.com/n8tb1t/use-scroll-position","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n8tb1t%2Fuse-scroll-position","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n8tb1t%2Fuse-scroll-position/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n8tb1t%2Fuse-scroll-position/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n8tb1t%2Fuse-scroll-position/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/n8tb1t","download_url":"https://codeload.github.com/n8tb1t/use-scroll-position/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243569030,"owners_count":20312348,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hooks","react","react-hooks","scroll","scroll-position"],"created_at":"2024-07-30T19:02:34.273Z","updated_at":"2025-09-27T12:58:25.069Z","avatar_url":"https://github.com/n8tb1t.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# `use-scroll-position`\n\n[![Node version](https://img.shields.io/npm/v/@n8tb1t/use-scroll-position.svg?style=flat)](https://www.npmjs.com/package/@n8tb1t/use-scroll-position)\n[![Node version](https://img.shields.io/npm/dw/@n8tb1t/use-scroll-position)](https://www.npmjs.com/package/@n8tb1t/use-scroll-position)\n[![Node version](https://img.shields.io/github/license/n8tb1t/use-scroll-position.svg?style=flat)](https://github.com/n8tb1t/use-scroll-position/blob/master/LICENSE)\n\n![Screenshot](https://github.com/n8tb1t/use-scroll-position/raw/master/examples/screenshot.png)\n\n`use-scroll-position` is a React [hook](https://reactjs.org/docs/hooks-reference.html) that returns the browser viewport X and Y scroll position. It is highly optimized and using the special technics to avoid unnecessary rerenders!\n\n\u003e It uses the default react hooks rendering lifecycle, which allows you to fully control its behavior and prevent unnecessary renders.\n\n\n## Important Update Notice\n\n**Starting from v1.0.44 the project has moved to typescript.**\n\nAlso, some bugs have been fixed, and thanks to our contributors we added an option to **track the scroll position of specified element inside some custom container**.\n\n\u003e Just pass the `element` reference and the `boundingElement` - (parent container) reference and track their corresponding position!  (`boundingElement` should be scrollable with overflow hidden or whatever)\n\n## Demo\n\n- [Hide navbar on scroll](https://n8tb1t.github.io/use-scroll-position/navbar/navbar)\n- [Hide/Show sidebar on scroll](https://n8tb1t.github.io/use-scroll-position/navbar/sidebar)\n- [Display viewport scroll position](https://n8tb1t.github.io/use-scroll-position/navbar/position)\n\n[![Edit use-scroll-position](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/use-scroll-position-8nfin?fontsize=14)\n\n## Install\n```\nyarn add @n8tb1t/use-scroll-position\n```\n\n## Usage\n\n```jsx\nuseScrollPosition(effect,deps, element, useWindow, wait)\n```\n\n| Arguments | Description |\n| --------- | ----------- |\n`effect`    | Effect callback.\n`deps`      | For effects  to fire on selected dependencies change.\n`element`      | Get scroll position for a specified element by reference.\n`useWindow`      | Use `window.scroll` instead of `document.body.getBoundingClientRect()` to detect scroll position.\n`wait`      | The `timeout` in ms. Good for performance.\n`boundingElement` | Only works with `useWindow` set to false, Just pass the `element` reference and the `boundingElement` - (parent container) reference and track their corresponding position, `boundingElement` should be scrollable with overflow hidden or whatever\n\n\u003e The `useScrollPosition` returns `prevPos` and `currPos`.\n\n## Examples\n\n**Log current scroll position**\n```jsx\nimport { useScrollPosition } from '@n8tb1t/use-scroll-position'\n\nuseScrollPosition(({ prevPos, currPos }) =\u003e {\n  console.log(currPos.x)\n  console.log(currPos.y)\n})\n```\n**Change state based on scroll position - Inline CSS**\n```jsx\nimport React, { useState } from 'react'\nimport { useScrollPosition } from '@n8tb1t/use-scroll-position'\n\nconst [headerStyle, setHeaderStyle] = useState({\n  transition: 'all 200ms ease-in'\n})\n\nuseScrollPosition(\n  ({ prevPos, currPos }) =\u003e {\n    const isVisible = currPos.y \u003e prevPos.y\n\n    const shouldBeStyle = {\n      visibility: isVisible ? 'visible' : 'hidden',\n      transition: `all 200ms ${isVisible ? 'ease-in' : 'ease-out'}`,\n      transform: isVisible ? 'none' : 'translate(0, -100%)'\n    }\n\n    if (JSON.stringify(shouldBeStyle) === JSON.stringify(headerStyle)) return\n\n    setHeaderStyle(shouldBeStyle)\n  },\n  [headerStyle]\n)\n\nconst Header = \u003cheader style={{ ...headerStyle }} /\u003e\n```\n\n**Change state based on scroll position - Styled Components**\n```jsx\nimport React, { useState } from 'react'\nimport { useScrollPosition } from '@n8tb1t/use-scroll-position'\n\nconst [hideOnScroll, setHideOnScroll] = useState(true)\n\nuseScrollPosition(({ prevPos, currPos }) =\u003e {\n  const isShow = currPos.y \u003e prevPos.y\n  if (isShow !== hideOnScroll) setHideOnScroll(isShow)\n}, [hideOnScroll])\n```\n**Get scroll position for custom element**\n```jsx\n  const [elementPosition, setElementPosition] = useState({ x: 20, y: 150 })\n  const elementRef = useRef()\n\n    // Element scroll position\n  useScrollPosition(\n    ({ currPos }) =\u003e {\n      setElementPosition(currPos)\n    }, [], elementRef\n  )\n```\n\n## Why to use\n`use-scroll-position` returns the scroll position of the browser window, using a modern, stable and performant implementation.\n\nMost of the time scroll listeners do very expensive work, such as querying dom elements, reading height / width and so on.\n`use-scroll-position` solves this by using [`throttling`](https://stackoverflow.com/a/44779316) technic to avoid too many reflows (the browser to recalculate everything).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fn8tb1t%2Fuse-scroll-position","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fn8tb1t%2Fuse-scroll-position","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fn8tb1t%2Fuse-scroll-position/lists"}