{"id":27440298,"url":"https://github.com/olarsson/react-scrollsy","last_synced_at":"2025-08-17T14:39:51.600Z","repository":{"id":191158515,"uuid":"677091220","full_name":"olarsson/react-scrollsy","owner":"olarsson","description":"An ambitious light-weight react module written in TypeScript for tracking scroll progress in a performant way. Developed for use with spring based animation libraries such as react-spring, but can be used with or without any library.","archived":false,"fork":false,"pushed_at":"2024-07-09T14:29:42.000Z","size":169,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-30T05:22:16.325Z","etag":null,"topics":["animate","animation","nextjs-scrollreveal","react","react-animate-on-scroll","react-scroll","react-scroll-motion","react-spring","reactscroll","scroll","scroll-animation","scroll-effect","scroll-reveal","scroll-reveal-animations","scroll-trigger","scrolling","scrollprogress","scrollreveal","scrolltrigger"],"latest_commit_sha":null,"homepage":"https://olarsson.github.io/react-scrollsy-examples/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/olarsson.png","metadata":{"files":{"readme":"README.md","changelog":"history.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-08-10T18:02:36.000Z","updated_at":"2025-04-21T07:19:38.000Z","dependencies_parsed_at":"2023-08-28T12:40:05.429Z","dependency_job_id":"818f2551-50e1-419e-a88e-5868011f48b8","html_url":"https://github.com/olarsson/react-scrollsy","commit_stats":null,"previous_names":["olarsson/react-scrollsy"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/olarsson/react-scrollsy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/olarsson%2Freact-scrollsy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/olarsson%2Freact-scrollsy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/olarsson%2Freact-scrollsy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/olarsson%2Freact-scrollsy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/olarsson","download_url":"https://codeload.github.com/olarsson/react-scrollsy/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/olarsson%2Freact-scrollsy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270861518,"owners_count":24658590,"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","status":"online","status_checked_at":"2025-08-17T02:00:09.016Z","response_time":129,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["animate","animation","nextjs-scrollreveal","react","react-animate-on-scroll","react-scroll","react-scroll-motion","react-spring","reactscroll","scroll","scroll-animation","scroll-effect","scroll-reveal","scroll-reveal-animations","scroll-trigger","scrolling","scrollprogress","scrollreveal","scrolltrigger"],"created_at":"2025-04-14T22:39:47.492Z","updated_at":"2025-08-17T14:39:51.537Z","avatar_url":"https://github.com/olarsson.png","language":"TypeScript","readme":"# react-scrollsy v1.2 ![](https://img.badgesize.io/olarsson/react-scrollsy/master/dist/react-scrollsy.es.js)\n\nAn ambitious light-weight react module written in TypeScript for tracking scroll progress in a performant way. Developed for use with spring based animation libraries such as react-spring, but can be used with or without any library.\n\n## Live demo / Code examples\n\nLive demo: https://olarsson.github.io/react-scrollsy-examples/\n\nCode examples: https://github.com/olarsson/react-scrollsy-examples/tree/master/src\n\n## Repository\n\nURL: https://github.com/olarsson/react-scrollsy\n\n## Installation\n\n    npm i react-scrollsy\n\n## Usage\n\nHere is a very basic example that tracks the scroll progress of the document.\n\n```js\nimport { ScrollTrackerDocument, ScrollTracker } from \"react-scrollsy\";\n\nimport { ScrollData, ScrollObject } from \"react-scrollsy/dist/types\";\n\nimport { useRef } from \"react\";\n\nfunction App() {\n  const refPageProgress = useRef(null);\n\n  return (\n    \u003cScrollTrackerDocument scrollThrottle={33}\u003e // 1000 ms/30 fps = 33ms, limits the triggered events to 30 fps, optional\n      {({ scrollData }: ScrollData) =\u003e {\n        return (\n          \u003cScrollTracker\n            scrollData={scrollData}\n            elem={refPageProgress}\n            settings={{\n              duration: {\n                distance: 100,\n                unit: \"%\",\n                basedOn: \"doc\",\n              },\n            }}\u003e\n            {({ scrollObject }: ScrollObject) =\u003e {\n              return \u003ch1 ref={refPageProgress}\u003eHere is the scroll progress: {scrollObject.progress}\u003c/h1\u003e;\n            }}\n          \u003c/ScrollTracker\u003e\n        );\n      }}\n    \u003c/ScrollTrackerDocument\u003e\n  );\n}\n\nexport default App;\n```\n\n## Usage without TypeScript\n\nYou don't use TypeScript? No problem, it's not a requirement. Simply remove the type declarations and it will work just fine. For example:\n\n```js\n      {({ scrollData }: ScrollData) =\u003e {\n        return (...);\n      }}\n```\n\nbecomes:\n\n```js\n      {({ scrollData }) =\u003e {\n        return (...);\n      }}\n```\n\n## Components\n\n### `\u003cScrollTrackerDocument /\u003e`\n\nSets the document as the main scrolling container.\nThis or ScrollTrackerCustom must always be the parent of a ScrollTracker component.\n\nConfiguration and properties:\n\n- `scrollThrottle` - (number) throttles the recalculations in ms to this value when the document is scrolled.\n- `resizeThrottle` - (number) throttles the recalculations in ms to this value when the document is resized.\n\nCreates a function which returns a `scrollData` object as such:\n\n- `scrollData` - (object, immutable) data returned from the component.\n  - `scrollTop` - (number, px) the scroll position from the top.\n  - `containerHeight` - (number, px) height of the container.\n  - `element` - (number, px) the tracked element for scrolling (document).\n  - `percentProgress` - (number, %) scroll progress in percent expressed as a number between 0 to 1.\n  - `scrollHeight` - (number, px) the total scrollable height of the document.\n\n```js\n\u003cScrollTrackerDocument\u003e\n  {({ scrollData }: ScrollData) =\u003e {\n    return (\n      // ScrollTracker components and other components can go inside here\n    );\n  }}\n\u003c/ScrollTrackerDocument\u003e\n```\n\n### `\u003cScrollTrackerCustom /\u003e`\n\nSets a custom element as the main scrolling container.\nThis or ScrollTrackerDocument must always be the parent of a ScrollTracker component.\n\nConfiguration and properties:\n\n- `scrollThrottle` - (number) throttles the recalculations to this value in ms when the element is scrolled.\n- `resizeThrottle` - (number) throttles the recalculations to this value in ms when the element is resized.\n- `scrollingElement` - (string/ref, required) the selector for the main scrollable element to track scroll progress of.\n\nCreates a function which returns a `scrollData` object as such:\n\n- `scrollData` - (object, immutable) data returned from the component.\n  - `scrollTop` - (number, px) the scroll position from the top.\n  - `containerHeight` - (number, px) height of the container.\n  - `element` - (number, px) the tracked element for scrolling (custom element).\n  - `percentProgress` - (number, %) scroll progress in percent expressed as a number between 0 to 1.\n  - `scrollHeight` - (number, px) the total scrollable height of the document.\n\n```js\n\u003cScrollTrackerCustom\n  key={active.toString()} // forces a rerender of the tracker, use this if you for example hide the element with 'display: none' combined with a string based scrollingElement selector\n  scrollingElement='#custom-scroll-container' // this can also be a ref such as scrollingElement={scrollRef}\n  \u003e\n  {({ scrollData }: ScrollData) =\u003e {\n    return (\n      // ScrollTracker components and other components can go inside here\n    );\n  }}\n\u003c/ScrollTrackerCustom\u003e\n```\n\n### `\u003cScrollTracker /\u003e`\n\nA specific DOM element and its progress based on its duration and offsets will be managed by this component.\n\nConfiguration and properties:\n\n- `elem` - (ref, required) sets the element reference to use when tracking scroll progress.\n- `settings` - (object, required)\n  - `trigger` - (['onEnter' | 'onLeave'], optional) when the calculations should be begin, defaults to 'onEnter'. is only used when 'basedOn' is set to 'elem' or 'vp'. 'onEnter' means the trigger is when the element enters the vp, 'onLeave' is when the element start to leave the vp.\n  - `duration` - (object, required)\n    - `distance` - (number, required) how long of the tracked elements duration calculations should be active for.\n    - `unit` - (['px' | '%'], required) unit the distance should be measured in.\n    - `basedOn` - (['doc' | 'elem' | 'vp'], required) the duration will be calculated based on distance + unit and what you chose here. 'doc' is the document, 'elem' is the element, 'vp' is the viewport height.\n  - `offsetTop` - (object, optional)\n    - `...` - same props as the duration.\n  - `offsetBottom` - (object, optional)\n    - `...` - same props as the duration.\n- `onStart` - (function, optional) callback to run when scroll progress begins.\n- `onEnd` - (function, optional) callback to run when scroll progress ends.\n\nCreates a function which returns a `scrollObject` object as such:\n\n- `scrollObject` (object, immutable) - data returned from the component.\n  - `scrollData` - (object, immutable) inherited from the main component.\n  - `progress` - (number, %) scroll progress in percent expressed as a number between 0 to 1.\n  - `start` - (number, px) the start position in pixels when scroll progress calculation should begin.\n  - `end` - (number, px) the end position in pixels when scroll progress calculation should end.\n\n```js\n\u003cScrollTracker\n  scrollData={scrollData} // the scrollData object returned by either ScrollTrackerDocument or ScrollTrackerCustom\n  elem={refElem}\n  settings={{\n    trigger: 'onLeave',\n    duration: {\n      distance: 100,\n      unit: \"%\",\n      basedOn: \"elem\",\n    },\n    offsetTop: {\n      distance: 25,\n      unit: \"%\",\n      basedOn: \"vp\",\n    },\n    offsetBottom: {\n      distance: -200,\n      unit: \"px\",\n      basedOn: \"\", // when using px this can be left empty\n    },\n  }}\u003e\n  {({ scrollObject }: ScrollObject) =\u003e {\n    return (\n      // return for example the scrollObject.progress to reflect progress, and any other elements/components that you wish\n    )\n  }}\n\u003c/ScrollTracker\u003e\n```\n\n### Next.js\nIf you load react-scrollsy as a dynamic component it will work out of the box, if you want it to work with SSR then you need to change your next config accordingly:\n```js\nconst nextConfig = {\n  transpilePackages: ['react-scrollsy']\n};\n```\nIf it still doesnt work then change the import string in the following fashion:\n`import { ScrollTrackerDocument, ScrollTracker } from \"node_modules/react-scrollsy/dist/react-scrollsy.es\";`\n\n\n### Todo\n\n- [ ] Implement the scroll logic for horizontal scrolling\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Folarsson%2Freact-scrollsy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Folarsson%2Freact-scrollsy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Folarsson%2Freact-scrollsy/lists"}