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
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 images in a wrapper having an height
, position:relative or absolute
and overflow: hidden
The images 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>
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 image 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 image 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 image height gap value in percentage that ensures it can always properly parallax. Any image 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 image 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>
<img class="parallax" data-center="0.2" data-intensity="10" data-safe-height="0.2" src="path/to/the/image.jpg" />
</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 image:loaded
and images: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:
image:loaded
: when a parallax image gets completely loadedimages:loaded
: when all the images get loadeddraw
: when a parallax image comes in the viewport and gets movedresize
: when the parallax images get resizedupdate
: when the page is scrolling and the script has updated all the visible images
p.on('image:loaded', function(image){
// do something with the image tag
})
Parallax.off
Stop listening an internal Parallax event
var fn = function (image) {
// do something with the image tag just drawn
p.off('draw', fn) // stop listening the draw event
}
p.on('draw', fn)
Parallax.refresh
Refresh the position of the images visible in the viewport
// do extremely heavy dom updates
p.refresh()
Parallax.add
Add new images to the parallax instance
// inject new images
p.add('.parallax-2')
Parallax.remove
Remove images from the parallax instance
p.remove('.parallax-2') // remove the images 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`