Rallax.js

Dead-simple parallax scrolling.

See a demo.

Usage

Follow these steps to get started:

1. Overview
2. Install
3. Import
4. Call
5. Review Options

Overview

Rallax.js creates a parallax effect given a target HTML element and an image location. It will create an <img> element, and position it absolute behind your target element.

As the user scrolls, the position of the <img> element will change relative to the target's location, creating the desired effect.

Install

Using NPM, install rallax, and save it to your package.json dependencies.

$ npm install rallax.js --save

Import

Import Rallax, naming it according to your preference.

import rallax from 'rallax.js'

Call

To generate the desired effect, call rallax, passing in your target-selector, image location, and your desired options.

// target:            <div class="parallax"></div>
// image location:    "./test-image.jpg"

const options = {
	speed: 0.5
}

rallax(".parallax", "./test-image.jpg", options)

Note: Rallax.js does not make any assumptions regarding the styling of the target element. In order to see the effect while using a background-color, you must set some degree of transparency. Additionally, if there are no contents inside the target, you will need to set a width and height.

Options

You are not required to pass any options. All options come with sensible defaults, shown below:

{
  speed: 0.3,
  zIndex: -1000,
	minPixels: 1024
}

Explanation of each option follows:

• speed
• adjust
  • scale
  • offset
• zIndex
• minPixels
• maxPixels

speed

Accepts an integer between 0 and 1.

At a speed of 0, the image will scroll with the target.
At a speed of 1, the image will appear fixed in place.

Please Note: higher speeds will demand much more from the browser, resulting in occasional 'chop' on older devices.

adjust

Accepts an object, specifying the scale and offset.

Either of these options can go unspecified. If scale is not specified, it defaults to the original size of the image. If offset is not specified, the image will be centered vertically and horizontally.

Note: if the image is not large enough to cover the full width and height of your HTML target, the adjust options will be ignored, and the image will be enlarged to just barely fit the target.

scale

Accepts an integer.

When manually adjusting your parallax image, it will start at a scale of 1 (the original size of your image). You can specify a different scale here.

// scale the image to half it's original size

rallax(".parallax", "./test-image.jpg", {
  adjust: {
    scale: 0.5
	}
})

offset

Accepts an object.

The offset option works similar to the background-position CSS property. offset will specify the center of the image relative to the target element.

offset is declared with two of the following keys: top, bot, left, right, followed by a an integer representing the number of pixels.

// position the center of the image 10px from the top of the
// target, and 40 px from the left.

rallax(".parallax", "./test-image.jpg", {
  adjust: {
		offset: {			
			top: 10,
			left: 40
		}
  }
})

// by default, the image will be centered relative to the target

rallax(".parallax", "./test-image.jpg")

zIndex

Accepts an integer.

zIndex specifies the z-index property of the parallax image.

maxPixels

Accepts an integer, specifying the maximum pixel width of the screen before 'turning off' the parallax effect.

Set maxPixels if you would like to turn off the parallax effect for very large screens.

Once turned off, the parallax image will appear as a background image for the target.

minPixels

Accepts an integer, specifying the minimum pixel width of the screen before 'turning on' the parallax effect.

Set minPixels if you would like to turn off the parallax effect for very small screens (such as mobile devices).

Once turned off, the parallax image will appear as a background image for the target.

Browser Support

Rallax depends on the following browser APIs:

• requestAnimationFrame

Consequently, it supports the following natively:

• Chrome 24+
• Firefox 23+
• Safari 6.1+
• Opera 15+
• IE 10+
• iOS Safari 7.1+

License

MIT. © 2018 Christopher Cavalea