README
smooth-scroll-operator
A dead simple and lightweight library to animate the scroll of the window or any HTMLElement.
No need to ask, he's a smooth operator...
- Really small filesize, only 1 dependency (~3KB uncompressed, including dependencies).
- Supports Beizer Curves and custom easing functions, with predefined values.
- Custom timing function (uses RAF by default if available)
- Pause/resume/stop/restart
- Animations respect the actual clock, so no matter the frame rate, the animation will still properly last the appropriate amount of time.
Installation
NPM:
npm i smooth-scroll-operator
browser:
You can use either smooth-scroll-operator.umd.js
or smooth-scroll-operator.min.umd.js
from the latest release in a script
tag.
This includes all dependencies.
<script src="smooth-scroll-operator.min.umd.js"></script>
<script>
SmoothScrollOperator.scrollY(window, 500);
</script>
Example Usage
import sso from 'smooth-scroll-operator';
let el = document.querySelector('.myElement');
//scroll el to 500
sso.scrollY(el, 500);
// Scroll to y = 500, with a duration of 200ms, and a custom cubic-bezier easing function:
sso.scrollY(el, 500, {
duration: 200,
easing: [0.42, 0.0, 0.58, 1.0]
});
// Scroll to y = 500, with a duration of 200ms, and a pre-defined easing function.
sso.scrollY(el, 500, {
duration: 200,
easing: sso.EASING.EASE_IN
});
//scroll window
sso.scrollY(window, 500);
//Scroll and then pause animation 300ms later.
let animation = sso.scrollY(el, 500);
setTimeout(() => {
animation.pause();
}, 300);
//resume 400ms later.
setTimeout(() => {
animation.resume();
}, 400);
//Scroll and then immediately stop animation
let animation = sso.scrollY(window, 500);
animation.stop();
API
scrollY({HTMLElement|window} el, {number} targetY, {object=} options)
Animates the scrolling of a given element (scrolls to target position). Returns an instance of DOMAnimate.
You can stop, pause, or resume the animation by calling .stop()
, .pause()
, or .resume()
, respectively, on the returned instance.
{HTMLElement} el
The element to scroll. Can be window
.
{number} targetY
The y position to animate/scroll to in pixels.
{object=} options
An optional map of parameters:
{integer} duration
Animation duration in milliseconds. (Default: 400
)
{array} easing
An array to pass to the cubic-bezier easing function. (Default: SmoothScrollOperator.EASE_IN_OUT
)
{function} onComplete
A callback function that is called when the animation is finished.
Constants
EASING
smooth-scroll-operator
ships with a small Bezier Curve library:
EASING.EASE
EASING.EASE_IN
EASING.EASE_OUT
EASING.EASE_IN_OUT
EASING.LINEAR
License
MIT. Free to use in all your things!
Contribution
DO IT! PR's welcome. Need to add testing, linting, and support for scrollX
, or both x/y at the same time.