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

File Size: 51.5 MB
Views Total: 37446
Last Update:
Publish Date:
Official Website: Go to website
License: MIT
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="">

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

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

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"
     <img class="jarallax-img" src="bg.jpg" alt="">

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

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

// Or jQuery
  // 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 class="jarallax" data-jarallax-video="https://vimeo.com/VIDEO ID HERE">

<div class="jarallax" data-jarallax-video="mp4:./1.mp4,webm:./1,ogv:./1.ogv">
  HTML5 Video
// Or Via JavaScript
jarallax(document.querySelectorAll('.jarallax'), {

// Or Via jQuery

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">

<!-- 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">

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

// check if is visible

// fit image and clip parallax container

// calculate parallax image position


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.