scrollimation
TypeScript icon, indicating that this package has built-in type declarations

3.0.1 • Public • Published

Scrollimation

A flexible library for animation of elements on scroll.

NPM Version License Travis (.org) npm bundle size (minified + gzip) Code style: prettier

Getting Started

Install

npm i -S scrollimation

Or load via CDN.

<script type="text/javascript" src="https://unpkg.com/scrollimation"></script>

Usage

import Scrollimation from "scrollimation";
 
let instance = new Scrollimation({
  target: "#target",
  from: 0,
  to: 100,
  step: function (state) {
    let rotate = state.calc(0, 180);
    let opacity = state.calc(1, 0);
 
    state.target[0].style.transform = `rotate(${rotate}deg)`;
    state.target[0].style.opacity = opacity;
  },
});

Options

target

Default Type
undefined HTMLElement | NodeList | Array | String

Stores the value in the state. If it is a NodeList it is converted to an Array. You can leave this parameter empty.

new Scrollimation({
  target: document.querySelector("#target"),
  from: 0,
  to: 100,
  step: (state) => {
    state.target.style.opacity = state.calc(1, 0);
  },
});

scrollContainer

Default Type
window HTMLElement | String

Change this value if it is assumed that the scroll position does not depend on page scrolling.

new Scrollimation({
  target: document.querySelector("#target"),
  scrollContainer: document.querySelector("#container"),
  from: 0,
  to: 100,
  step: (state) => {
    state.target.style.opacity = state.calc(1, 0);
  },
});

from

Default Type
0 Number

The scroll position from which animation begins. In step function with current scroll position state.calc returns a value equal to its first parameter.

new Scrollimation({
  target: document.querySelector("#target"),
  from: 100,
  to: 200,
  step: (state) => {
    state.target.style.opacity = state.calc(1, 0);
  },
});

to

Default Type
0 Number

The scroll position from which animation ends. In step function with current scroll position state.calc returns a value equal to its second parameter.

new Scrollimation({
  target: document.querySelector("#target"),
  from: 0,
  to: 100,
  step: (state) => {
    state.target.style.opacity = state.calc(1, 0);
  },
});

direction

Default Type
top Number

Use if you need an animation on the horizontal scrolling.

new Scrollimation({
  target: document.querySelector("#target"),
  from: 0,
  to: 100,
  duration: "left",
  step: (state) => {
    state.target.style.opacity = state.calc(1, 0);
  },
});

easing

Default Type
linear String | Function

Determines the acceleration curve of your animation.

constant accelerate decelerate accelerate-decelerate
linear easeInQuad easeOutQuad easeInOutQuad
easeInCubic easeOutCubic easeInOutCubic
easeInQuart easeOutQuart easeInOutQuart
easeInQuint easeOutQuint easeInOutQuint

You can use custom function:

new Scrollimation({
  target: document.querySelector("#target"),
  from: 0,
  to: 100,
  easing: (val) => val * val,
  step: (state) => {
    state.target.style.opacity = state.calc(1, 0);
  },
});

Also you can use for each state.calc different easing function:

new Scrollimation({
  target: document.querySelector("#target"),
  from: 0,
  to: 100,
  step: (state) => {
    state.target.style.opacity = state.calc(1, 0, "easeInOutQuad");
  },
});

mode

Default Type
requestAnimationFrame String

If your animation is too heavy, you can try using mode: 'onscroll'.

new Scrollimation({
  target: document.querySelector("#target"),
  from: 0,
  to: 100,
  mode: "onscroll",
  step: (state) => {
    state.target.style.opacity = state.calc(1, 0);
  },
});

fpsLimit

Default Type
undefined Number

If your animation is too heavy, you can also limits the number of animation steps per second. (with undefined value FPS will be around 60)
You can try to combine this with mode: 'onscroll'.

new Scrollimation({
  target: document.querySelector("#target"),
  from: 0,
  to: 100,
  fpsLimit: 30,
  step: (state) => {
    state.target.style.opacity = state.calc(1, 0);
  },
});

step

Default Type
() => {} Function

This function is called to redraw animated elements. The parameter is an instance of the animation. Inside the animation instance, you can use the state.calc function, using which you can calculate the animated values.

new Scrollimation({
  target: document.querySelector("#target"),
  from: 0,
  to: 100,
  step: (state) => {
    state.target.style.opacity = state.calc(1, 0);
    // if scrollTop === state.from (0) state.calc(1, 0) return 1
    // else if scrollTop === state.to (100) state.calc(1, 0) return 0
  },
});

init

Default Type
() => {} Function

This function is called when Scrollimation initialize current animation instance when the animation is not already running.

new Scrollimation({
  target: document.querySelector("#target"),
  from: 0,
  to: 100,
  step: (state) => {
    state.target.style.opacity = state.calc(1, 0);
  },
  init: (state) => {
    console.log("Animation instance initialized!");
  },
});

start

Default Type
() => {} Function

This function called when the animation begins when the scroll position is state.from. (Only while scrolling from state.from to state.to)
It called before the first step function is called.

new Scrollimation({
  target: document.querySelector("#target"),
  from: 0,
  to: 100,
  step: (state) => {
    state.target.style.opacity = state.calc(1, 0);
  },
  start: (state) => {
    console.log("Current scroll position is " + state.from);
  },
});

end

Default Type
() => {} Function

This function called when the animation ends when the scroll position is state.to. (Only while scrolling from state.from to state.to)
It called after the last step function is called.

new Scrollimation({
  target: document.querySelector("#target"),
  from: 0,
  to: 100,
  step: (state) => {
    state.target.style.opacity = state.calc(1, 0);
  },
  end: (state) => {
    console.log("Current scroll position is " + state.to);
  },
});

reverseStart

Default Type
() => {} Function

This function called when the reverse animation begins when the scroll position is state.to. (Only while scrolling from state.to to state.from)

new Scrollimation({
  target: document.querySelector("#target"),
  from: 0,
  to: 100,
  step: (state) => {
    state.target.style.opacity = state.calc(1, 0);
  },
  reverseStart: (state) => {
    console.log("Current scroll position is " + state.to);
  },
});

reverseEnd

Default Type
() => {} Function

This function called when the reverse animation ends when the scroll position is state.from. (Only while scrolling from state.to to state.from)

new Scrollimation({
  target: document.querySelector("#target"),
  from: 0,
  to: 100,
  step: (state) => {
    state.target.style.opacity = state.calc(1, 0);
  },
  reverseEnd: (state) => {
    console.log("Current scroll position is " + state.from);
  },
});

Additional functions

stop

Stops the animation.

let instance = new Scrollimation({
  target: document.querySelector("#target"),
  from: 0,
  to: 100,
  step: (state) => {
    state.target.style.opacity = state.calc(1, 0);
  },
});
 
instance.stop();

play

Starts the stopped animation.

let instance = new Scrollimation({
  target: document.querySelector("#target"),
  from: 0,
  to: 100,
  status: "pause",
  step: (state) => {
    state.target.style.opacity = state.calc(1, 0);
  },
});
 
instance.play();

remove

Removes the animation handler permanently. Use if playing animation is never needed again.

new Scrollimation({
  target: document.querySelector("#target"),
  from: 0,
  to: 100,
  status: "pause",
  step: (state) => {
    state.target.style.opacity = state.calc(1, 0);
 
    if (document.body.scrollTop === state.to) state.remove(); // Animation is played only once.
  },
});
 
instance.play();

Running the tests

npm test

Author

License

This project is licensed under the MIT License - see the LICENSE file for details

Readme

Keywords

Package Sidebar

Install

npm i scrollimation

Weekly Downloads

1

Version

3.0.1

License

MIT

Unpacked Size

115 kB

Total Files

16

Last publish

Collaborators

  • rinor