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:

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`