Tiny Parallax Background Plugin In JavaScript - Parlx.js

parlx is an extremely lightweight jQuery/Vanilla JavaScript plugin used to create parallax scrolling effects by altering the background position using CSS3 2D transforms (translateY).

Key Features:

• Supports any parallax content: images, videos, divs, etc.
• Supports vertical, horizontal, diagonal directions.
• Allows to disable parallax effect on selected user agents.
• Also supports foreground parallax scrolling effect.

Installation:

# NPM
$ npm install parlx.js --save

How to use it:

1. Import the Parlx.js as an ES module.

import Parlx from 'parlx.js';

2. Or include the parlx plugin's script at the bottom of the webpage.

<!-- As a vanilla JS plugin -->
<script src="/path/to/lib/parlx.min.js"></script>
<!-- As a jQuery plugin -->
<script src="/path/to/cdn/jquery.slim.min.js"></script>
<script src="/path/to/lib/parlx.js"></script>

3. Add a parallax object (image, video, div, etc) with the CSS class of '' to your parallax container.

<section class="parallax">
  <div class="parlx-children" style="background-image: url(1.jpg);">
  </div>
</section>

4. The example CSS styles.

.parallax {
  z-index: 10;
  position: relative;
  height: 400px;
  overflow: hidden;
}

.bgimg {
  position: absolute;
  background-repeat: no-repeat;
  background-size: cover;
}

5. Activate the parallax scrolling effect by calling the function on the parallax container.

// As a vanilla JS plugin
const elems = document.querySelectorAll('.parallax');
const parlx = new Parlx(elems, {
      // options here
});

// As a jQuery plugin -->
$('.parallax').parlx({
  // options here
});

6. Or use the data-parlx attribute to initialize the plugin without any JS call.

<section class="parallax">
  <div class="bgimg parlx-children" style="background-image: url(1.jpg);" data-parlx>
  </div>
</section>

7. Adjust the default animation speed.

<div class="parallax" data-speed="0.1">
</div>

// OR As a vanilla JS plugin
const elems = document.querySelectorAll('.parallax');
const parlx = new Parlx(elems, {
      speed: 0.3
});

// OR As a jQuery plugin -->
$('.parallax').parlx({
  settings: {
    speed: 0.3
  }
});

8. Set custom height.

<div class="parallax" data-height="400px">
</div>

// OR As a vanilla JS plugin
const elems = document.querySelectorAll('.parallax');
const parlx = new Parlx(elems, {
      height: '700px'
});

// OR As a jQuery plugin -->
$('.parallax').parlx({
  settings: {
    height: '700px'
  }
});

9. Enable or disable the parallax scroll on selected user agents.

<div class="bgimg" data-exclude="/(iPod|iPhone|iPad|Android)/">
</div>

// OR As a vanilla JS plugin
const elems = document.querySelectorAll('.parallax');
const parlx = new Parlx(elems, {
      exclude: '/(Mozilla|iPad)/'
});

// OR As a jQuery plugin -->
$('.parallax').parlx({
  settings: {
    exclude: '/(Mozilla|iPad)/'
  }
});

10. Set the direction of the parallax scrolling.

<div class="bgimg" data-direction="vertical">
</div>

// OR As a vanilla JS plugin
const elems = document.querySelectorAll('.parallax');
const parlx = new Parlx(elems, {
      direction: 'vertical', // or horizontal, diagonal'
});

// OR As a jQuery plugin -->
$('.parallax').parlx({
  settings: {
    direction: 'vertical', // or horizontal, diagonal
  }
});

11. Apply the parallax effect to any DIV.

<div class="parallax" data-type="foreground">
</div>

// OR As a vanilla JS plugin
const elems = document.querySelectorAll('.parallax');
const parlx = new Parlx(elems, {
      type: 'foreground'
});

// OR As a jQuery plugin -->
$('.parallax').parlx({
  settings: {
     type: 'foreground'
  }
});

12. Set the observed scroll element & scroll axis

// As a vanilla JS plugin
const elems = document.querySelectorAll('.parallax');
const parlx = new Parlx(elems, {
      base: window,
      axis: 'y'
});

// As a jQuery plugin -->
$('.parallax').parlx({
  settings: {
    base: window,
    axis: 'y'
  }
});

13. Callback functions available.

// As a vanilla JS plugin
const elems = document.querySelectorAll('.parallax');
const parlx = new Parlx(elems, {
      onInit: el => { /* code */ }
      onDestroy: el => { /* code */ }
      onResize: el => { /* code */ }
      onScroll: el => { /* code */ }
});

// As a jQuery plugin -->
$('.parallax').parlx({
  callbacks: {
    onInit: el => { /* code */ }
    onDestroy: el => { /* code */ }
    onResize: el => { /* code */ }
    onScroll: el => { /* code */ }
  }
});

14. Destroy the plugin.

elems.parlx.destroy();

Changelog:

v3.0.0 (2020-05-16)

• Added axis option
• Added base option
• Added full access to library methods for jQuery
• Added overscroll protection (mobile & Safari)
• Fixed incorrect background scaling
• Fixed exclude option incorrect behavior
• Rewritten with TypeScript
• Renamed data-* to data-parlx-*
• Rename helpers
• Updated demo

v2.0.4 (2019-04-12)

• Fix incorrect scrolling behavior in Edge

v2.0.3 (2019-03-22)

• fixed CDN undefined bug

v2.0.0 (2019-03-07)

• auto init is active only if element with data-parlx exists
• create .parlx-children if not exists
• reenabled auto init
• reenabled jQuery support
• Doc update

v1.3.1 (2018-10-07)

• new callbacks: onScroll, onResize

v1.3.0 (2018-07-16)

• switched from Gulp to Webpack
• updated Babel to v7
• only 2 dist version
• changed main file from parlx.js to parlx.min.js
• moved demo to gh-pages branch

v1.2.0 (2018-07-08)

• added support for all HTML5 tags as parallax div children

v1.1.0 rc 1 (2018-06-10)

• redesigned demo page (new header view, dark theme)
• re-added support for image tag as a background
• added autoinit
• fixed parallax background size bug
• updated README.md
• renamed jQuery plugin from Parlx() to parlx()
• code cleaned up
• renamed type option values (back to background and front to foreground)
• added parlxMove event
• fixed bug with autoinit in Node.js
• fixed bug with jQuery and Node.js compatibility
• updated dependencies

2018-01-15

• JS update

2018-01-15

• Bugfix

2017-12-06

• v4.0

2017-11-29

• v3.1.1: Code cleaned up

2017-10-14

• v2.1.1

2017-08-25

• v2.0.13

---

This awesome jQuery plugin is developed by parlx-js. For more Advanced Usages, please check the demo page or visit the official website.