af-scroll v1.1.1

AFScroll (Animation Frame Scroll)

The script aligns page scroll update with animation frame.
It allows to perform js based DOM manipulation related to page scroll just in time, not too late.

Demo

Menu

• Quick start
• Features
• Disadvantages
• Why you may need AFScroll?
• Options
• Methods
• Events

Quick start

Install

# install af-scroll npm package
npm install --save af-scroll

Initialization

// import create function
import createAFScroll from 'af-scroll';

// call to initialize
createAFScroll();

Imports

The library build is delivered in two formats: esmodule and commonjs

// default import (esmodule)
import createAFScroll from 'af-scroll';

// explicit import (esmodule)
import createAFScroll from 'af-scroll/dist/esmodule';

// explicit import (commonjs)
const createAFScroll = require('af-scroll/dist/commonjs');

Features

• alignment of js on scroll updates with the visual scroll update
• on scroll updates throttled by requestAnimationFrame
• native scroll triggers (native scrollbar, mouse wheel, keyboard, touch)
• scroll smoothing (optional)
• scroll locking (optional)

Disadvantages

• additional wrapping element in DOM
• missing support for native scroll to results of find on page

Why you may need AFScroll?

If you want to manipulate DOM elements by js and set them based on the scroll position.

What happens when you use default scroll:

• user scrolls a page
• browser renders new scroll position
• user sees new scroll position
• the native on scroll event is triggered
• js updates for current scroll position
  (any custom DOM manipulations by js)
• user sees DOM elements updated by js

What happens when you use AFScroll:

• user scrolls a page
• browser renders new scroll position
• user not sees new scroll position
• the native on scroll event is triggered
• js updates for current scroll position
  (update visible scroll position & any custom DOM manipulations by js)
• user sees new scroll position & DOM elements updated by js in the same time

Options

createAFScroll({
  smoothForce: 0.8,
  smoothLimit: 0.2,
  scrollEl: null,
  className: 'afScroll',
  wrapExclude: 'script, link',
  autoHeight: 12,
  onUpdate: () => {},
  onComplete: () => {},
});

1. prevents DOM modification by auto created wrapper, passed scrollEl will be used instead of it
2. ignored if scrollEl passed

Methods

// example of using methods
const afScroll = createAFScroll(/* optional options */);
afScroll.scrollTo(0); // scroll to top
afScroll.scrollTo(0, true); // scroll to top forced
afScroll.free(); // free forced scroll
afScroll.lock(); // lock scroll
afScroll.unlock(); // unlock scroll
afScroll.destroy(); // destroy af-scroll
afScroll.init(); // reinit af-scroll

Events

createAFScroll({
  onUpdate: (scroll) => {
    // custom behavior
  },
  onComplete: (scroll) => {
    // custom behavior
  },
});