smooth-parallax

Smooth Parallax

Parallax that doesn't suck! No jQuery required, just plain 'ol javascript.

Smooth Parallax makes it easy to move objects when you scroll, being it images, divs or what-have-you. Use it to add that background or foreground parallax effect to your website or create a moving scene with a hippie van :)

Enjoy using Smooth Parallax?

If you enjoy using Smooth Parallax and want to say thanks, you can leave me a small tip. All payments are securely handled through PayPal.

Installation

Setting up is pretty straight-forward. Just download the script from dist folder and include it in your HTML:

<script type="text/javascript" src="path/to/smooth-parallax.min.js"></script>

Smooth Parallax also supports AMD / CommonJS

// AMD
require(["path/to/smooth-parallax"], function(SmoothParallax) {});

// CommonJS
var SmoothParallax = require("smooth-parallax");

NPM / Bower

Smooth Parallax is also available on NPM and Bower:

npm install smooth-parallax      # npm
bower install smooth-parallax    # bower

Basic Usage

Init

Just call SmoothParallax.init() to get objects moving and configure elements movement.

<script type="text/javascript">
  window.addEventListener("load", function () {
    SmoothParallax.init();
  });
</script>

Smooth Parallax will automatically look for all objects with the attribute smooth-parallax (ie.: <img src="images/hippie-van.png" smooth-parallax="">).

Configure elements movement

You'll also have to set at least one more attribute start-position or end-position, see options at standard options.

Standard Options

Global Options

These options are passed to the init function when starting Smooth Parallax.

• basePercentageOn Set how you want to track scroll percentage:
  • containerVisibility default: scroll percentage for each moving object is calculated only when the element's container is visible in the viewport. This prevents objects from moving while not visible.
  • pageScroll: scroll percentage is based on the page scroll and is the same for all moving objects.

Elements Options

These options are passed as html attributes to the moving elements and define how that element movement behaves.

All percentage values are in decimal form, ie.: 1 = 100%. You can also set values greater than 1 and smaller than 0, ie.: -0.5 = -50% or 1.25 = 125%.

• start-movement - define at what scroll percentage to start moving the object. Default value is 0.0;
• end-movement - define at what scroll percentage to stop moving the object. Default value is 1.0.
• start-position-x - define the horizontal start position of the element in percentage of its the base-size (see option below).
• start-position-y - define the vertical start position of the element in percentage of its the base-size (see option below).
• end-position-x - define the horizontal end position of the element in percentage of its the base-size (see option below).
• end-position-y - define the vertical end position of the element in percentage of its the base-size (see option below).
• container - change the elements container element user to calculate its position, default is moving element's parent node.
• base-size - define how to calculate the base size of the movement, used to calculate the target position.
  • elementSize: calculate based on the element size itself.
  • containerSize: calculate based on the elements container size.

Contributing to Development

This isn't a large project by any means, but I'm definitely welcome to any pull requests and contributions.

You can get your copy up and running for development quickly by cloning the repo and running npm:

$ npm install

This will install all the necessary tools for compiling minified files.

Change Log

1.1.2

• Improvement: Extend public method getScrollPercent to return scroll percentage for elements.
• Fix: issue calculating element's size for SVG on Firefox
• Fix: position calculation to 2 decimals precision for better performance.
• Fix: scroll percent calculation based on containerSize.

1.1.1

• Fix npm package.json info.

1.1.0

Upgrade Notice: This version changes how Smooth Parallax is initiated and how the elements options are set.

• Converted script into a javascript plugin.
• Renamed html attributes:
  • data-smooth-parallax-element > smooth-parallax
  • data-start-percent > start-movement
  • data-end-percent > end-movement
  • data-start-x > start-position-x
  • data-start-y > start-position-y
  • data-end-x > end-position-x
  • data-end-y > end-position-y
  • data-smooth-parallax-element > smooth-parallax
  • data-container-id > container.
• Changed element option container expected value to be a valid css selector instead of element id.
• Added element option base-size.
• Added global option pageScroll.

1.0.0

• Initial release

License

Licensed under MIT. Enjoy.

Acknowledgement

Smooth Parallax was created by Diego Versiani for a better Parallax Effect.