[![Build Status][travis-image]][travis-url]
[![NPM version][npm-version-image]][npm-url]
[![NPM downloads][npm-downloads-image]][npm-url]
[![MIT License][license-image]][license-url]
[![Coverage Status][coverage-image]][coverage-url]
[![Code Quality][codeclimate-image]][codeclimate-url]

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

``sh
$ 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

`html










`

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

`js
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:

`js
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:

`html






`

API

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

$3

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

$3

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

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

$3

Stop listening an internal Parallax event

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

$3

Refresh the position of the elements visible in the viewport

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

$3

Add new element to the parallax instance

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

$3

Remove element from the parallax instance

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

$3

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

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

Contributing

Available tasks

$3


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

$3

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

$3

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

$3

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

$3

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

[travis-image]:https://img.shields.io/travis/GianlucaGuarini/parallax.svg?style=flat-square
[travis-url]:https://travis-ci.org/GianlucaGuarini/parallax

[license-image]:http://img.shields.io/badge/license-MIT-000000.svg?style=flat-square
[license-url]:LICENSE

[npm-version-image]:http://img.shields.io/npm/v/scroll-parallax.svg?style=flat-square
[npm-downloads-image]:http://img.shields.io/npm/dm/scroll-parallax.svg?style=flat-square
[npm-url]:https://npmjs.org/package/scroll-parallax

[coverage-image]:https://img.shields.io/coveralls/GianlucaGuarini/parallax/master.svg?style=flat-square
[coverage-url]:https://coveralls.io/r/GianlucaGuarini/parallax?branch=master

[codeclimate-image]:https://api.codeclimate.com/v1/badges/05d33fcf100bac2cb67f/maintainability
[codeclimate-url]:https://codeclimate.com/github/GianlucaGuarini/parallax