https://github.com/olarsson/react-scrollsy
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.
https://github.com/olarsson/react-scrollsy
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
Last synced: 14 days ago
JSON representation
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.
- Host: GitHub
- URL: https://github.com/olarsson/react-scrollsy
- Owner: olarsson
- Created: 2023-08-10T18:02:36.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2024-07-09T14:29:42.000Z (10 months ago)
- Last Synced: 2025-04-03T15:50:43.652Z (25 days ago)
- 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
- Language: TypeScript
- Homepage: https://olarsson.github.io/react-scrollsy-examples/
- Size: 165 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: history.md
Awesome Lists containing this project
README
# react-scrollsy v1.2 
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.
## Live demo / Code examples
Live demo: https://olarsson.github.io/react-scrollsy-examples/
Code examples: https://github.com/olarsson/react-scrollsy-examples/tree/master/src
## Repository
URL: https://github.com/olarsson/react-scrollsy
## Installation
npm i react-scrollsy
## Usage
Here is a very basic example that tracks the scroll progress of the document.
```js
import { ScrollTrackerDocument, ScrollTracker } from "react-scrollsy";
import { ScrollData, ScrollObject } from "react-scrollsy/dist/types";
import { useRef } from "react";
function App() {
const refPageProgress = useRef(null);
return (
// 1000 ms/30 fps = 33ms, limits the triggered events to 30 fps, optional
{({ scrollData }: ScrollData) => {
return (
{({ scrollObject }: ScrollObject) => {
return
Here is the scroll progress: {scrollObject.progress}
;
}}
);
}}
);
}
export default App;
```
## Usage without TypeScript
You don't use TypeScript? No problem, it's not a requirement. Simply remove the type declarations and it will work just fine. For example:
```js
{({ scrollData }: ScrollData) => {
return (...);
}}
```
becomes:
```js
{({ scrollData }) => {
return (...);
}}
```
## Components
### ``
Sets the document as the main scrolling container.
This or ScrollTrackerCustom must always be the parent of a ScrollTracker component.
Configuration and properties:
- `scrollThrottle` - (number) throttles the recalculations in ms to this value when the document is scrolled.
- `resizeThrottle` - (number) throttles the recalculations in ms to this value when the document is resized.
Creates a function which returns a `scrollData` object as such:
- `scrollData` - (object, immutable) data returned from the component.
- `scrollTop` - (number, px) the scroll position from the top.
- `containerHeight` - (number, px) height of the container.
- `element` - (number, px) the tracked element for scrolling (document).
- `percentProgress` - (number, %) scroll progress in percent expressed as a number between 0 to 1.
- `scrollHeight` - (number, px) the total scrollable height of the document.
```js
{({ scrollData }: ScrollData) => {
return (
// ScrollTracker components and other components can go inside here
);
}}
```
### ``
Sets a custom element as the main scrolling container.
This or ScrollTrackerDocument must always be the parent of a ScrollTracker component.
Configuration and properties:
- `scrollThrottle` - (number) throttles the recalculations to this value in ms when the element is scrolled.
- `resizeThrottle` - (number) throttles the recalculations to this value in ms when the element is resized.
- `scrollingElement` - (string/ref, required) the selector for the main scrollable element to track scroll progress of.
Creates a function which returns a `scrollData` object as such:
- `scrollData` - (object, immutable) data returned from the component.
- `scrollTop` - (number, px) the scroll position from the top.
- `containerHeight` - (number, px) height of the container.
- `element` - (number, px) the tracked element for scrolling (custom element).
- `percentProgress` - (number, %) scroll progress in percent expressed as a number between 0 to 1.
- `scrollHeight` - (number, px) the total scrollable height of the document.
```js
{({ scrollData }: ScrollData) => {
return (
// ScrollTracker components and other components can go inside here
);
}}
```
### ``
A specific DOM element and its progress based on its duration and offsets will be managed by this component.
Configuration and properties:
- `elem` - (ref, required) sets the element reference to use when tracking scroll progress.
- `settings` - (object, required)
- `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.
- `duration` - (object, required)
- `distance` - (number, required) how long of the tracked elements duration calculations should be active for.
- `unit` - (['px' | '%'], required) unit the distance should be measured in.
- `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.
- `offsetTop` - (object, optional)
- `...` - same props as the duration.
- `offsetBottom` - (object, optional)
- `...` - same props as the duration.
- `onStart` - (function, optional) callback to run when scroll progress begins.
- `onEnd` - (function, optional) callback to run when scroll progress ends.
Creates a function which returns a `scrollObject` object as such:
- `scrollObject` (object, immutable) - data returned from the component.
- `scrollData` - (object, immutable) inherited from the main component.
- `progress` - (number, %) scroll progress in percent expressed as a number between 0 to 1.
- `start` - (number, px) the start position in pixels when scroll progress calculation should begin.
- `end` - (number, px) the end position in pixels when scroll progress calculation should end.
```js
{({ scrollObject }: ScrollObject) => {
return (
// return for example the scrollObject.progress to reflect progress, and any other elements/components that you wish
)
}}
```
### Next.js
If 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:
```js
const nextConfig = {
transpilePackages: ['react-scrollsy']
};
```
If it still doesnt work then change the import string in the following fashion:
`import { ScrollTrackerDocument, ScrollTracker } from "node_modules/react-scrollsy/dist/react-scrollsy.es";`
### Todo
- [ ] Implement the scroll logic for horizontal scrolling