https://github.com/builtbyjonas/paralux
Physics-driven smooth scroll & parallax engine
https://github.com/builtbyjonas/paralux
animation javascript library parallax paralux physics react scroll
Last synced: 3 months ago
JSON representation
Physics-driven smooth scroll & parallax engine
- Host: GitHub
- URL: https://github.com/builtbyjonas/paralux
- Owner: builtbyjonas
- License: mit
- Created: 2026-04-01T15:47:13.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-02T16:16:18.000Z (3 months ago)
- Last Synced: 2026-04-03T03:32:34.731Z (3 months ago)
- Topics: animation, javascript, library, parallax, paralux, physics, react, scroll
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/paralux
- Size: 219 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Codeowners: CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# Paralux
**Paralux** is a modern, high-performance, physics-driven scroll engine designed for React, Next.js, and vanilla web applications. It replaces native scrolling with a fully controllable virtual scroll system, enabling smooth interpolation, inertia, parallax effects, and scroll-based animations.
> [!CAUTION]
> Paralux is still in early development. The API is not yet stable and may change without a major version bump. Use with caution in production environments and expect breaking changes as the library evolves.
## Features
- **Smooth Scrolling Engine:** Virtual scroll layer using `requestAnimationFrame`.
- **Physics System:** Built-in Spring and LERP physics mechanics mimicking native iOS-like inertia.
- **Parallax System:** Attribute-based or programmatic parallax mapping.
- **Auto-Recalculation:** Smart viewport caching using `ResizeObserver` & `MutationObserver` ensures your scroll limits never break during dynamic DOM updates.
- **WebGL / GPU Sync:** Built-in `.webgl` plugin syncing scroll vectors and mathematically deduced `skew` limits natively to your shaders.
- **React Support First-Class:** Includes a robust set of typed providers and hooks.
## Installation
```bash
npm install paralux normalize-wheel
# or
pnpm add paralux normalize-wheel
```
_(Note: `normalize-wheel` is required for virtual scroll hijacking)_
## Quick Start (Vanilla)
```ts
import { Paralux } from "paralux";
import { parallax, velocity } from "paralux/modules";
const paralux = new Paralux({
smooth: true,
virtualScroll: true,
physics: "spring",
stiffness: 150,
damping: 20,
});
paralux.use(parallax());
paralux.use(velocity());
```
## Quick Start (React)
```tsx
import { ParaluxProvider, Parallax, useParalux } from "paralux/react";
export default function App() {
return (
This moves half as fast!
{/* Your App */}
);
}
```
## Documentation
For a deep dive into the APIs and advanced usage, see the `docs/` directory:
- [Getting Started](docs/getting-started.md)
- [Core API Reference](docs/api.md)
- [Available Plugins](docs/plugins.md)
- [React Reference](docs/react.md)
- [Physics & WebGL Guide](docs/physics-and-webgl.md)
---
**License**: MIT
**Author**: ByJonas / Jonas Franke