Tiny Parallax Background Plugin In JavaScript - Parlx.js

File Size: 105 KB
Views Total: 12454
Last Update:
Publish Date:
Official Website: Go to website
License: MIT
   
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.