Scrawler v1.2.0

A javascript library for monitoring vertical scroll events.

Scrawler is a simple library to help react users’ scroll events. As it is for people who want a super-simple, barebone library for scroll events, it only provides position data for baselines and DOM elements. All the fancy animations, parallax effect, and/or any other visual effects should be coded manually. However, if you don’t like any magic and do want to keep full control of your code, this is the right library for you. To see how Scrawler works in production, please refer to this list.

Download

Installation

Option 1: HTML

<script src="Scrawler.min.js"></script>

Option 2: Node.js & npm

In terminal, execute:

$ npm i scrawler --save

and import in JS:

var Scrawler = require('scrawler'); // CommonJS

or alternatively:

import Scrawler from 'scrawler'; // ES6

Quick Start

After downloading Scrawler.js, use below code to quick-start:

<!DOCTYPE html>
<html>
  <body style="height:200vh">
    <style>.unit-to-track {height:25vh;margin:20px;border:4px solid #000}</style>
    <div class="unit-to-track"></div>
    <div class="unit-to-track"></div>
    <div class="unit-to-track"></div>
    <div class="unit-to-track"></div>
    <script src="Scrawler.js"></script>
    <script>
      var scrawler = new Scrawler();
      scrawler.add({el: '.unit-to-track'}, function(){
        this.el.innerHTML = this.progress.px + 'px apart from viewport center.';
      }).run();
    </script>
  </body>
</html>

Architecture

Scrawler consists of two main objects, Logic and Unit.

Scrawler
|
+-- Logic
|   |
|   +-- Unit
|
+-- Logic
|   |
|   +-- Unit
|   +-- Unit
|
+-- Logic 
|   |
|   +-- Unit
|   +-- Unit
|   +-- Unit
.

Logic

Logic is a coded logic that explains how certain DOM elements should react based on scroll events. Therefore, when creating Logic (.add()), it is required to assign at least one DOM element (args.el) and define what to do with it (callback). The created Logic will be added and stored in the Scrawler instance.

Unit

When a Logic is created, Unit objects are automatically created based on Logic’s assigned DOM element (args.el) info. The number of created Units is identical to the number of DOM elements selected by the args.el. The created Units will be added and stored in the Logic instance.

Unit is a piece of information about a single DOM element and its baseline, current position, etc. Its position data is constantly updated by the Logic that the Unit belongs to.

APIs

Scrawler()

Scrawler constructor. Initialization of Scrawler is required to begin.

Syntax:

new Scrawler( [settings] )

Arguments:

settings {object} (optional) Scrawler settings for initialization.

Parameters for settings:

Parameter	Type	Default	Description
`baseline`	integer or string	'center'	`Scrawler`'s baseline position. All `Units` will reference this `baseline`. If an integer value is used, it means pixel distance from the top of the viewport. Percentage values (i.e. `'50%'`) or f values (i.e. `'0.5f'`) in strings mean relative position from viewport. Alternatively, `'top'`/`'center'`/`'bottom'` can be also used instead of `'0%'`/`'50%'`/`'100%'` or `'0f'`/`'0.5f'`/`'1f'`, respectively.
`idling`	integer	0	Number of additional rounds that `window.requestAnimationFrame()` is called after scroll stops. If this value is `-1`, it will be always running regardless of scroll. Usually, there is no need to render additional frames after scroll stops.

Example 1:

var scrawler = new Scrawler();

Example 2:

var scrawler = new Scrawler({ baseline: 500 });

Example 3:

var scrawler = new Scrawler({ baseline: '0.5f' });

Example 4:

var scrawler = new Scrawler({ baseline: '50%' });

Example 5:

var scrawler = new Scrawler({ baseline: 'center' });

.add()

Add a Logic to Scrawler.

Syntax:

.add( settings, callback, [callback_arguments] )

Arguments:

settings {object} Settings for a Logic.

Parameters for settings:

Parameter	Type	Default	Description
`el`	string	-	[REQUIRED] Query selector string for target DOM elements.
`range`	Array(2)	-	Range where the `Logic` will be executed. The first and the second array value stand for the starting position and the ending position of the `Logic` respectively. Both array values can have either integer or string. Integer stands for pixel value. String value should be a specific format such as `0%` to `100%` (percentage values), or `0f` to `100f` (fraction values). If `range` is not assigned, the `Logic` will be executed at any range, from `-INFINITY` to `+INFINITY`. To run the `Logic` only when the DOM meets the viewport baseline, assign `['0%', '100%']` or `['0f', '1f']` for this range value.
`id`	string	(random value)	(optional) ID for the `Logic`. Required to remove this `Logic` later with `Scrawler.remove()` method.
`baseline`	integer or string	0	The DOM element's baseline position. `Scrawler` measures the distance between the viewport baseline and this baseline. If an integer value is used, it means pixel distance from the top of the viewport. Percentage (i.e. `'50%'`) or f values (i.e. `'0.5f'`) in strings mean relative position from viewport. Alternatively, `'top'`/`'center'`/`'bottom'` can be also used instead of `'0%'`/`'50%'`/`'100%'` or `'0f'`/`'0.5f'`/`'1f'`, respectively.
`order`	integer	0	Running order of `Logic` objects. Bigger order number will run later.

callback {function} This function is called on each DOM element selected by args.el when scroll events happen. In this callback function, this is a current Unit object that Scrawler is rendering on.
callback_arguments {Array} (optional) parameters for callback function.

Return: {Scrawler} Scrawler object

Example 1:

scrawler.add({
  el: '.scrawler-unit'
}, function(){
  console.log(this.progress.px); // prints current progress in pixel value.
});

Example 2:

scrawler.add({
  el: '.scrawler-unit',
  range: ['0f', '1f'],
  baseline: 'center'
}, function(arg1, arg2){
  console.log(arg1 + this.progress.px + arg2); // prints "progress: [...]px"
}, ['progress: ', 'px']);

Example 3:

scrawler.add({
  el: '.scrawler-unit',
  range: ['0%', '100%'],
  baseline: 'center'
}, function(arg1, arg2){
  console.log(arg1 + this.progress.px + arg2); // prints "progress: [...]px"
}, ['progress: ', 'px']);

.remove()

Remove a Logic from Scrawler.

Syntax:

.remove( logic_id )

Arguments:

logic_id {string} ID for the target Logic to remove. Only Logics with IDs can be removed. An ID can be assigned when a Logic is created.

Return: {Scrawler} Scrawler object

Example:

scrawler.add({
  id: 'myLogicID',
  el: '.scrawler-unit'
}, function(){...});

...

scrawler.remove('myLogicID');

.sort()

Sort Logics based on order value. order values can be set up when creating each Logic with .add(). The bigger order value a Logic has, the later it runs.

Syntax:

.sort()

Return: {Scrawler} Scrawler object

Example:

scrawler
.add({
  id: 'paintRed', 
  el: '.scrawler-unit',
  order: 1 
  }, function(){
    document.body.style.background = 'red';
  })
.add({
  id: 'paintBlue', 
  el: '.scrawler-unit',
  order: 0 
  }, function(){
    document.body.style.background = 'blue';
  })
.sort() // by sorting Logics, `paintRed` will be called after `paintBlue`.
.run(); // `paintBlue` will always be overwritten by `paintRed`.

.run()

Start/resume Scrawler to run added logics.

This function creates a requestAnimationFrame loop and call assigned Logics internally. To run Scrawler in an already existing rAF, use .watch() method instead.

Syntax:

.run()

Return: {Scrawler} Scrawler object

Example 1:

scrawler
.add({ el: '.scrawler-unit' }, function(){...})
.run();

Example 2:

scrawler
.add({ el: '.scrawler-unit' }, function(){...});

...

scrawler.run();

.pause()

Pause Scrawler. Only works to .run(), not watch().

Usually useful only when idling setting is -1 or big enough. Scrawler automatically pauses after reaching the assigned idling number. Scrawler will automatically resume when the user starts scrolling again. To stop Scrawler permanently after calling .run(), it is required to remove Scrawler instance (i.e. scrawler = null;).

Syntax:

.pause()

Return: {Scrawler} Scrawler object

Example:

scrawler
.add({ el: '.scrawler-unit' }, function(){...})
.run();

...

scrawler.pause();

.watch()

Initialize and run Scrawler in an existing requestAnimationFrame. Works as same as run(), but calling watch() in an existing rAF will run Scrawler without creating another rAF.

This method is for advanced use cases. run() method would work for most circumstances.

Syntax:

.watch()

Return: {Scrawler} Scrawler object

Example:

scrawler.add({ el: '.scrawler-unit' }, function(){...});

...

window.requestAnimationFrame(raf_worker);

function raf_worker() {
  scrawler.watch();
  window.requestAnimationFrame(raf_worker);
}

.refresh()

Refresh all baseline and position values. Automatically called when resizing browsers.

Syntax:

.refresh()

Return: {Scrawler} Scrawler object

Example:

scrawler.refresh();

Scrawler.Logic()

A Logic contains information about how targeted DOM elements interact in accordance with the browser’s scroll positions. A Scrawler instance usually carries multiple Logics and call each Logic every time when a scroll event occurs.

Syntax:

new Scrawler.Logic( args, callback, [callbackArgs] )

Note: Logic is usually created by Scrawler.add(). Creating Logic directly using new Scrawler.Logic() is a very rare use case which is not recommended.

Arguments:

Refer to Scrawler.add().

Scrawler.Unit()

Unit objects are automatically created by Scrawler while adding a Logic to Scrawler. Each Unit indicates actual DOM elements monitored by Scrawler.

Unit objects are accessible by calling this instance in Scrawler.add() methods’ callback functions.

.el

DOM Element of the Unit that Scrawler is currently handling

Example:

scrawler
.add({ el: '#scrawler-elm' }, function(){
  console.log( this.el ); // document.getElementById('scrawler-elm')
});

.progress

Progress of the Unit in fraction (f), viewport fraction (vf), and pixel (px). All fraction values stand for unit intervals, from 0 to 1 range.

Example:

scrawler
.add({ el: '.scrawler-unit' }, function(){
  console.log(
    this.progress.f,  // progress in fraction
    this.progress.vf, // progress in viewport fraction
    this.progress.px  // progress in pixel
  );
});

.f()

Shorthand of Scrawler.Unit.progress.f.

Syntax:

.f()

Return: {float} Unit progress value in fraction.

Example:

scrawler
.add({ el: '.scrawler-unit' }, function(){
  console.log( this.f() );
});

.vf()

Shorthand of Scrawler.Unit.progress.vf.

Syntax:

.vf()

Return: {float} Unit progress value in viewport fraction.

Example:

scrawler
.add({ el: '.scrawler-unit' }, function(){
  console.log( this.f() );
});

.px()

Shorthand of Scrawler.Unit.progress.px.

Syntax:

.px()

Return: {integer} Unit progress value in pixel.

Example:

scrawler
.add({ el: '.scrawler-unit' }, function(){
  console.log( this.px() );
});

.scale()

Linear interpolate a range of values to another.

Syntax:

.scale( scale_id, scale_values, callback, [callbackArgs] )

Arguments:

scale_id {string} Unique ID for this .scale() call. Must assign an ID to use .scale(). Any unique string works.

scale_values {object} Scale range values to interpolate.

Parameters for scale_values :

Parameter	Type	Default	Description
`from`	Array(2)	-	[REQUIRED] Source range of interpolation. Both array values can have either integer or string. Integer stands for pixel value. String value should be a specific format such as `0%` to `100%` (percentage values), or `0f` to `1f` (fraction values).
`to`	Array(2)	`[0, 1]`	Target range of interpolation. Both array values should have integers.

callback {function(interpolated_value)} This function is called when current Unit’s progress is in source range (scale_values.from). The first argument of the callback is the interpolated value of current Unit’s progress.
callback_arguments {Array} (optional) parameters for callback function.

Return: void

Example 1:

scrawler
.add({ el: '.scrawler-unit' }, function(){
  this.scale('myScale', {
    from: [123, 456]
  }, function(val){
    console.log(val); // interpolated to [0, 1] scale
  });
});

Example 2:

scrawler
.add({ el: '.scrawler-unit' }, function(){
  this.scale('myScale', {
    from: [123, 456],
    to:   [7.89, 10]
  }, function(val){
    console.log(val); // interpolated value
  });
});

Example 3:

scrawler
.add({ el: '.scrawler-unit' }, function(){
  this.scale('myScale', {
    from: ['0.12f', '0.34f'],
    to:   [5, 6.78]
  }, function(val){
    console.log(val); // interpolated value
  });
});

Example 4:

scrawler
.add({ el: '.scrawler-unit' }, function(){
  this.scale('myScale', {
    from: ['12%', '34.5%'],
    to:   [60, 78]
  }, function(val){
    console.log(val); // interpolated value
  });
});

Scrawler.Position()

Position object contains a fraction value (f), a viewport fraction value (vf), and a pixel value (px). It is a standard format for any position values used in this library.

.f

Position value in fraction.

.vf

Position value in viewport fraction.

.px

Position value in pixel.

Live Links

Browser Support

Scrawler supports all major modern browsers including IE 10+.

License

MIT

briantjacobs/Scrawler

Scrawler v1.2.0

A javascript library for monitoring vertical scroll events.

Download

Installation

Option 1: HTML

Option 2: Node.js & npm

Quick Start

Architecture

Logic

Unit

APIs

Scrawler()

.add()

.remove()

.sort()

.run()

.pause()

.watch()

.refresh()

Scrawler.Logic()

Scrawler.Unit()

.el

.progress

.f()

.vf()

.px()

.scale()

Scrawler.Position()

.f

.vf

.px

Live Links

Browser Support

License