High-Performance Background Parallax Effect with jQuery and CSS3 - jarallax

Just another jQuery/JavaScript parallax plugin used for adding a smooth parallax scrolling effect to images, background images, Youtube/Vimeo/HTML5 videos and any HTML elements using CSS3 3D transforms (translate3d).

With a fallback to background-position when CSS transforms are not supported.

Basic usage:

1. Load the jarallax plugin in the HTML page. jQuery library is OPTIONAL.

<!-- jQuery (OPTIONAL) -->
<script src="/path/to/cdn/jquery.min.js"></script>
<!-- Core -->
<script src="/path/to/dist/jarallax.js"></script>
<!-- Video Support -->
<script src="/path/to/dist/jarallax-video.js"></script>
<!-- Custom Element Support -->
<script src="/path/to/dist/jarallax-element.js"></script>

2. Add a parallax image to the container as follows.

<!-- img tag -->
<div class="jarallax">
  <img class="jarallax-img" src="bg.jpg" alt="">
</div>

<!-- picture tag -->
<div class="jarallax">
  <picture class="jarallax-img">
    <source media="(max-width: 650px)" srcset="bg-alt.jpg">
    <img src="bg.jpg" alt="">
  </picture>
</div>

<!-- background image -->
<div class="jarallax" style="background-image: url('bg.jpg');">
</div>

3. The required CSS styles for the background image.

.jarallax {
  position: relative;
  z-index: 0;
}
.jarallax > .jarallax-img {
  position: absolute;
  object-fit: cover;
  /* support for plugin https://github.com/bfred-it/object-fit-images */
  font-family: 'object-fit: cover;';
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  z-index: -1;
}

4. The fatest way to initialize the parallax plugin is to add the data-jarallax attribute to the parallax container. You can pass the configuration options via data-OPTION attributes as follows:

<div class="jarallax"
     data-jarallax
     data-OPTIONNAME="VALUE">
     <img class="jarallax-img" src="bg.jpg" alt="">
</div>

5. You can also initialize the parallax plugin via JavaScript:

// Vanilla JavaScript
jarallax(document.querySelectorAll('.jarallax'), {
  // options here
});

// Or jQuery
$('.jarallax').jarallax({
  // options here
});

6. Apply the parallax scroll effect to a video:

<div class="jarallax" data-jarallax-video="https://www.youtube.com/watch?v=VIDEO ID HERE">
  Youtube Video
</div>

<div class="jarallax" data-jarallax-video="https://vimeo.com/VIDEO ID HERE">
  Vimeo
</div>

<div class="jarallax" data-jarallax-video="mp4:./1.mp4,webm:./1,ogv:./1.ogv">
  HTML5 Video
</div>

// Or Via JavaScript
jarallax(document.querySelectorAll('.jarallax'), {
  videoSrc: 'VIDEO SOURCE HERE'
});

// Or Via jQuery
$('.jarallax').jarallax({
  videoSrc: 'VIDEO SOURCE HERE'
});

7. Apply the parallax scroll effect to an HTML element:

<!-- Element will be parallaxed on -150 pixels from the screen center by Y axis -->
<div data-jarallax-element="-150">
  ...
</div>

<!-- Element will be parallaxed on 300 pixels from the screen center by Y axis and on -150 pixels from the screen center by X axis -->
<div data-jarallax-element="300 -150">
  ...
</div>

8. All default configuration options.

// scroll, scale, opacity, scale-opacity, scroll-opacity
type: 'scroll',

// animation speed
speed: 0.5, 

// image parallax scroll effect
imgSrc: null,
imgElement: '.jarallax-img',
imgSize: 'cover',
imgPosition: '50% 50%',
imgRepeat: 'no-repeat', 

// keep <img> tag in it's default place
keepImg: false, 

// use custom DOM / jQuery element to check if parallax block in viewport.
elementInViewport: null,

// z-index property
zIndex: -100,

// disable parallax scroll effect on certain devices
// e.g. disableParallax: /iPad|iPhone|iPod|Android/
disableParallax: false,

// disable video parallax scroll effect on certain devices
// e.g. disableParallax: /iPad|iPhone|iPod|Android/
disableVideo: false,

// use ResizeObserver API to recalculate position and size of parallax image
automaticResize: true, 

// video options
videoSrc: null,
videoStartTime: 0,
videoEndTime: 0,
videoVolume: 0,
videoLoop: true,
videoPlayOnlyVisible: true,
videoLazyLoading: true

9. Callback functions.

jarallax(document.querySelectorAll('.jarallax'), {
  onScroll: function(calculations) {},
  onInit: function() {},
  onDestroy: function() {},
  onCoverImage: function() {},
  // video extension
  onVideoInsert: function() {//this.$video},
  onVideoWorkerInit: function(videoWorkerObject) {}, 
});

10. API methods.

// Vanilla JS
// jarallax(document.querySelectorAll('.jarallax'), method);
// jQuery
// $('.jarallax').jarallax(method);

// destroy
$('.jarallax').jarallax('destroy');

// check if is visible
$('.jarallax').jarallax('isVisible');

// fit image and clip parallax container
$('.jarallax').jarallax('onResize');

// calculate parallax image position
$('.jarallax').jarallax('scroll');

Changelog:

v2.0.4 (2022-07-17)

• removed will-change usage

v2.0.2 (2022-02-17)

• added VideoWorker globally in video extension since some project uses it
• added browserslist-config-nk
• updated eslint and prettier configs

v2.0.1 (2022-02-11)

• dropped IE support (supported modern browsers only)
• added ESM, UMD, and CJS modules
• added new event callbacks to video extension: onVideoInsert, onVideoWorkerInit
• added prettier for code formatting
• removed clipContainer method, use modern clip-path styles instead
• removed check for transform with vendor prefixes

v1.12.8 (2021-10-21)

• include TS typings in dist
• changed standard position for mobile devices to 'fixed' (working smoother)

v1.12.7 (2021-05-12)

• removed postinstall script

v1.12.6 (2021-05-12)

• added accessibility attributes to background videos (tabindex, aria-hidden)

v1.12.5 (2020-11-29)

• added GDPR compliance parameters to Youtube and Vimeo API calls (in video-workers library)
• updated dependencies

v1.12.4 (2020-09-23)

• additional styles for video elements (prevent click on video blocks)
• fixed video loop and image reset problem

v1.12.3 (2020-09-22)

• fixed bug with clip images in Safari v14

v1.12.2 (2020-08-10)

• updated dependencies
• updated video-worker script 
• slightly changed styles, applied to container and to parallaxed images

v1.12.1 (2020-04-29)

• DEPRECATED Elements extension for Jarallax. Use laxxx instead
• added support for video error event (display image when error)
• added poster attribute for self-hosted videos
• fixed video background playing when disabled parallax only
• removed rafl dependency. Use native requestAnimationFrame instead

v1.12.0 (2019-10-23)

• added support for scrollable parents
• removed resize observer support (should work without it)

v1.11.1 (2019-10-01)

• fixed imgSrc option in JS initialization without actual <img> tag

---

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