![Code Quality](https://img.shields.io/codeclimate/github/GianlucaGuarini/parallax.svg?style=flat-square)
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
$ 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 3 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 |
You can set the Parallax options in this way:
var p = new Parallax('.parallax', {
offsetYBounds: 50,
intensity: 30,
center: 0.5
}).init()
Each image could be configured using custom Parallax options (except the offsetYBounds
) overriding the default:
<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" 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){
})
Parallax.off
Stop listening an internal Parallax event
var fn = function (image) {
p.off('draw', fn)
}
p.on('draw', fn)
Parallax.refresh
Refresh the position of the images visible in the viewport
p.refresh()
Parallax.add
Add new images to the parallax instance
p.add('.parallax-2')
Parallax.remove
Remove images from the parallax instance
p.remove('.parallax-2')
Parallax.destroy
Destroy the parallax instance removing all the internal and external callbacks to its internal events
p.destroy()
Contributing
Available tasks
Build and test
$ ./make
Convert the ES6 code into valid ES5 combining all the modules into one single file
$ ./make build
Run all the tests
$ ./make test
Start a nodejs static server
$ ./make serve
To compile and/or test the project anytime a file gets changed
$ ./make watch