Why

Oh no, why another parallax script? Do we really need it?

There are many parallax scripts but none of them was satisfying my personal needs:

No dependencies
No background positioning and heavy obtrusive DOM manipulations
Build only for modern devices without internal hacks
Modern and flexible api being thought mainly for ajax applications
Modern and clean ES6/2015 source code

So I decided to make my own and you can be free to use it or simply ignore it and move forward to the next one!

Demos

demo

Usage

Installation

$ npm install scroll-parallax --save
# or
$ bower install scroll-parallax --save

Markup and initialization

Once you have included the script in your page, you should wrap your parallax elements in a wrapper having an height, position:relative or absolute and overflow: hidden The elements will be stretched to fit always the whole wrapper size

<figure style="position: relative; height: 300px; overflow: hidden;">
  <img class="parallax" src="path/to/the/image.jpg" />
</figure>

<figure style="position: relative; height: 300px; overflow: hidden;">
  <video class="parallax" src="path/to/the/video.mp4" />
</figure>

The Parallax api is really simple and the following snippet should be enough:

var p = new Parallax('.parallax').init()

Options

The options available are only 4 at moment:

Type	Name	Default Value	Description
Number	`offsetYBounds`	50	the offset top and bottom boundaries in pixels used by the parallax to consider an element in the viewport
Number	`intensity`	30	the intensity of the parallax effect
Number	`center`	0.5	the vertical center of the parallax. If you increase this value the element will be centered more on the top of the screen reducing it will look centered at bottom this value should be between 0 and 1
Number	`safeHeight`	0.15	the safe element height gap value in percentage that ensures it can always properly parallax. Any element should be (by default) at least 15% higher than their DOM wrappers (7.5% bottom + 7.5% top)

You can set the Parallax options in this way:

var p = new Parallax('.parallax', {
  offsetYBounds: 50,
  intensity: 30,
  center: 0.5,
  safeHeight: 0.15
}).init()

Each element could be configured using custom Parallax options (except for the offsetYBounds) overriding the defaults:

<figure>
  <img class="parallax" data-center="0.8" data-intensity="50" src="path/to/the/image.jpg" />
</figure>
<figure>
  <video class="parallax" data-center="0.2" data-intensity="10" data-safe-height="0.2" src="path/to/the/video.mp4" />
</figure>

API

Each Parallax instance has some useful methods that could be used to adapt it to your application needs

Parallax.init

Initialize the parallax internal event listeners. The listeners to element:loaded and elements:loaded should be set before this method gets called

Parallax.on

The on method allows you to listen the internal Parallax events from the outside.
Currently it supports:

element:loaded: when a parallax elment gets completely loaded
elements:loaded: when all the elements to parallax get loaded
draw: when a parallax element becomes visible in the the viewport and starts getting moved
resize: when the window will be resized
update: when the page is scrolling and the script has updated all the visible elemens

p.on('element:loaded', function(element){
  // do something with the element
})

Parallax.off

Stop listening an internal Parallax event

var fn = function (element) {
    // do something with the elemnt just drawn
    p.off('draw', fn) // stop listening the draw event
  }
p.on('draw', fn)

Parallax.refresh

Refresh the position of the elements visible in the viewport

// do extremely heavy dom updates
p.refresh()

Parallax.add

Add new element to the parallax instance

// inject new elements
p.add('.parallax-2')

Parallax.remove

Remove element from the parallax instance

p.remove('.parallax-2') // remove the element from the parallax
// and also from the DOM...

Parallax.destroy

Destroy the parallax instance removing all the internal and external callbacks to its internal events

p.destroy() // the parallax is dead!

Contributing

Available tasks

Build and test

$ ./make # or also `$ npm run default`

Convert the ES6 code into valid ES5 combining all the modules into one single file

$ ./make build # or also `$ npm run build`

Run all the tests

$ ./make test # or also `$ npm run test`

Start a nodejs static server

$ ./make serve # or also `$ npm run serve`

To compile and/or test the project anytime a file gets changed

$ ./make watch # or also `$ npm run watch`

GianlucaGuarini/parallax

Why