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: () => {},
});

| Option | Type | Default | Description | | --- | --- | --- | --- | | smoothForce | Number | 0.8 | smoothing force in range 0.0 - 1.00: no smooth1: no scroll | | smoothLimit | Number | 0.2 | min diff between current and target value to keep smooth loop | | scrollEl | Element | null | static scroll wrapper element1 | | className | String | "afScroll" | css class name of scroll wrapper element2 | | wrapExclude | String | "script, link" | css selector to exclude from wrapping2 | | autoHeight | Number | 12 | height checking period in frames1: each frame0: disabled12: once per each 12 frames | | onUpdate | Function | () => {} | callback function triggered on scroll update | | onComplete | Function | () => {} | callback function triggered after smooth loop stopped |

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

| Method | Arguments | Return | Description | | --- | --- | --- | --- | | init() | none | undefined | reinitialize the script after destroy | | scrollTo(scroll, force) | scroll {Number} target scroll value in px unitforce {Boolean} prevents user from changing a scroll target until it completes | undefined | scroll to scroll value | | free() | none | undefined | free forced scroll | | lock() | none | undefined | lock scroll | | unlock() | none | undefined | unlock scroll | | destroy() | none | undefined | destroy the script and restore original html |

Events

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

| Event | Arguments | When triggered | | --- | --- | --- | | onUpdate(scroll) | scroll {Number} scroll value in px unit | in each animation frame of move to target scroll | | onComplete(scroll) | scroll {Number} scroll value in px unit | after achieve target scroll - smooth loop stopped |