📜 DEFINITIVE SCROLL ANIMATION GUIDE
VibeDev Scroll bridges the gap between declarative UI and high-performance WASM physics, allowing your interface to react to the momentum of the viewport.
1. useVibeScroll (Physics-Enhanced Metrics)
The useVibeScroll hook provides momentum-aware scroll data using real-time spring physics.
🛠️ Usage
const { scrollYProgress, velocity } = useVibeScroll({
smooth: true,
stiffness: 100,
damping: 30
});
🌟 Use Case
Physics-Lag Cursors: Creating a custom cursor that "lags" behind the scroll, or a 3D element that tilts based on the current scroll speed (measured in px/s).
⌨️ Demo Source
import { useVibeScroll, useTransform, vibe } from 'vibedev-motion';
function ScrollTilt() {
const { velocity } = useVibeScroll();
const rotateX = useTransform(velocity.y, [-1000, 1000], [-20, 20]);
return <vibe.div style={{ rotateX }}>I tilt as you scroll!</vibe.div>;
}
2. vibe Component: Parallax Shorthand
Instantly link any element's position or rotation to the global scroll progress with declarative props.
🛠️ Usage
<vibe.div parallax={{ y: -150, rotate: 10 }}>
Floating Asset
</vibe.div>
🌟 Use Case
Hero Sections: Floating background assets that move at different rates relative to the foreground text as the user scrolls.
⌨️ Demo Source
<vibe.section>
<vibe.img src="/bg.png" parallax={{ y: -200 }} />
<vibe.h1 parallax={{ y: -50, rotate: -2 }}>The Future</vibe.h1>
</vibe.section>
3. vibe Component: whileInView Physics
Trigger a physical impulse or global force exactly when an element enters the viewport.
🛠️ Usage
<vibe.div whileInView={{ opacity: 1, physics: 5 }}>
I pop into existence!
</vibe.div>
🌟 Use Case
Tactile "Pop" Effects: Use it for cards, buttons, or testimonial sections to add a physical "thud" or "bounce" when they scroll into view.
⌨️ Demo Source
<vibe.div
initial={{ opacity: 0, scale: 0.8 }}
whileInView={{
opacity: 1,
scale: 1,
physics: 8 // Intensity of the physical global impulse
}}
viewport={{ once: true }}
>
<Card />
</vibe.div>
4. VibeProgress (Momentum Progress Bar)
A highly responsive reading progress indicator with built-in spring physics and liquid momentum.
🛠️ Usage
<VibeProgress color="#00ffcc" height={5} position="top" smoothing={true} />
5. VibeHorizontalScroll (Physical Gallery)
Converts standard vertical scroll distance into a physical horizontal conveyor belt with inertia.
🛠️ Usage
<VibeHorizontalScroll intensity={1.2} gap={40}>
<img src="/p1.jpg" />
<img src="/p2.jpg" />
</VibeHorizontalScroll>
6. ScrollPhysics (Global Force Generator)
Turns every scroll "flick" into a physical force that affects all dynamic bodies currently in the simulation.
🛠️ Usage
<ScrollPhysics intensity={2.0} forceType="impulse" direction="vertical" />
🌟 Use Case
Living Backgrounds: Websites with floating interactive UI elements (like bubbles or leaves) that the user can "blow" around or displace by scrolling fast.
7. VibeParallaxLayer (Depth Physics)
A layer-based parallax system where elements move according to their calculated physical "depth."
🛠️ Usage
<VibeParallaxLayer depth={0.8} intensity={120}>
<ForegroundAsset />
</VibeParallaxLayer>
8. useVibeInView (Viewport Logic Core)
The core hook used to manually trigger physical events or script sequences when elements appear.
⌨️ Demo Source
function ExplodingSection() {
const ref = useRef(null);
useVibeInView(ref, {
physicsImpulse: 20,
once: true
});
return <div ref={ref}>The world shakes when I am seen!</div>;
}