Framework-agnostic toolkit for implementing smooth parallax and fade effects using the native ScrollTimeline API. Zero dependencies, maximum performance.
npm install @parallaxx/toolkitA lightweight, framework-agnostic toolkit for implementing smooth parallax and fade effects that leverage the native ScrollTimeline API.
✅ Minuscule footprint (5kb)
✅ Easy to use presets
✅ Maximum performance
Install the package via npm:
``
npm i @parallaxx/toolkit
`typescript`
// Import the ParallaxX class and optional preset enums
import { ParallaxX, TranslatePreset, OpacityPreset } from "@parallaxx/toolkit";
// Import the CSS
import "@parallaxx/toolkit/dist/parallaxx.css";
Initialize the ParallaxX class in your application.
If you're using React/Next.js, initialize it inside useLayoutEffect:
`jsx`
useLayoutEffect(() => {
new ParallaxX();
}, []);
For other frameworks or vanilla JavaScript, initialize the class after the DOM is ready.
Add data attributes to the elements you want to animate.
ParallaxX finds elements with 'data-pxx-translate' and 'data-pxx-opacity' attributes.
`jsx
data-pxx-opacity={OpacityPreset.FADE_IN}
>
$3
The toolkit provides several presets for convenience.
The three values represent the enter, middle (center of the viewport), and exit values of the animation.
typescript
enum TranslatePreset {
SLOWER = "50%,0%,-50%",
SLOW = "100%,0%,-100%",
FAST = "200%,0%,-200%",
FASTER = "300%,0%,-300%",
}enum OpacityPreset {
FADE_IN = "0,1,1",
FADE_IN_OUT = "0,1,0",
HALF_FADE_IN = "0.5,1,1",
HALF_FADE_IN_OUT = "0.5,1,0.5",
}
`jsx
data-pxx-opacity={OpacityPreset.FADE_IN_OUT}
>$3
For greater flexibility you can provide custom values.
These are comma-separated strings representing the enter, middle, and exit values.
Translate values can be anything that CSS translate3d supports.
Opacity values should range between 0 and 1.
jsx
// Translate the element from 120px to -120px as it moves through the view.
// Fade the element from 0.2 opacity to 1.0 as it reaches the center of the view.
// Translate the element from 10vh to -20vh as it moves through the view. Aligning in the center (0)
// Fade the element from 0 opacity to 1.0 as it reaches the center of the view, and then back out to 0.4 as it exits.
`#### Random Values
Values can be randomly generated too - which is useful for sets of mapped elements.
The format is "random(min|max)"
jsx
// The following will result in a random exit value between -10px and -200px
`$3
The range controls when the animation timeline starts and ends.
With cover (default) the timeline begins as the element starts to enter the view, and ends when it has completely left it.
With contain the timeline begins after the entire element has entered the view, and ends as it starts to leave.
You can customise these values to fine-tune the start and ending using different values.
typescript
export enum RangePreset {
COVER = "cover 0% cover 100%", // Default
CONTAIN = "contain 0% contain 100%",
}
``By utilizing native browser capabilities and minimizing reliance on JavaScript, ParallaxX outperforms animation frameworks that compute animations on the main thread.
If window.ScrollTimeline() is not supported, a polyfill is loaded.
This project is licensed under the MIT License.