Events and Methods

Jarallax provides a comprehensive API for controlling parallax instances through events and methods.

Methods

Methods allow you to programmatically control Jarallax instances after initialization.

destroy

Completely removes the Jarallax effect and restores the element to its original state.

JavaScript
jQuery

// Destroy specific elements
jarallax(document.querySelectorAll('.jarallax'), 'destroy');

// Destroy a single element
jarallax(document.querySelector('.jarallax'), 'destroy');

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

What destroy does

From the source code, the destroy method:

Removes the parallax observer
Restores original styles from data-jarallax-original-styles attribute
Moves the image element back to its original position (if using <img> tag)
Removes the parallax container element from the DOM
Calls the onDestroy callback if defined
Deletes the jarallax instance from the element

// From core.js
destroy() {
  const self = this;

  removeObserver(self);

  // return styles on container as before jarallax init
  const originalStylesTag = self.$item.getAttribute('data-jarallax-original-styles');
  self.$item.removeAttribute('data-jarallax-original-styles');
  if (!originalStylesTag) {
    self.$item.removeAttribute('style');
  } else {
    self.$item.setAttribute('style', originalStylesTag);
  }

  // ... restore image and remove container

  if (self.options.onDestroy) {
    self.options.onDestroy.call(self);
  }

  delete self.$item.jarallax;
}

After calling destroy, you’ll need to reinitialize Jarallax if you want to use it again on the same elements.

isVisible

Checks if the parallax element is currently visible in the viewport.

JavaScript
jQuery

const visible = jarallax(document.querySelector('.jarallax'), 'isVisible');

if (visible) {
  console.log('Parallax element is visible');
}

const visible = $('.jarallax').jarallax('isVisible');

if (visible) {
  console.log('Parallax element is visible');
}

Returns: boolean

This method returns true if the element is currently in the viewport, false otherwise.

onResize

Manually triggers the resize handler to recalculate and refit the parallax image.

JavaScript
jQuery

// Trigger resize on all parallax elements
jarallax(document.querySelectorAll('.jarallax'), 'onResize');

$('.jarallax').jarallax('onResize');

When to use onResize

Call onResize when:

The container element size changes dynamically
Content is loaded that affects layout
Window is resized programmatically
Elements are shown/hidden
Orientation changes on mobile devices

// Example: After loading dynamic content
fetch('/api/content')
  .then(response => response.json())
  .then(data => {
    document.querySelector('.jarallax').innerHTML = data.content;
    
    // Recalculate parallax after content loads
    jarallax(document.querySelector('.jarallax'), 'onResize');
  });

From the source code:

onResize() {
  this.coverImage();
}

onScroll

Manually triggers the scroll handler to recalculate the parallax image position.

JavaScript
jQuery

// Trigger scroll calculation
jarallax(document.querySelectorAll('.jarallax'), 'onScroll');

$('.jarallax').jarallax('onScroll');

Jarallax automatically calls this method on window scroll. You only need to call it manually if you’re programmatically scrolling or need to force a position update.

Method Examples

Conditional Destroy

// Initialize parallax
jarallax(document.querySelectorAll('.jarallax'), {
  speed: 0.5
});

// Later, destroy on mobile
if (window.innerWidth < 768) {
  jarallax(document.querySelectorAll('.jarallax'), 'destroy');
}

Dynamic Content Loading

// Initialize
jarallax(document.querySelectorAll('.jarallax'));

// After adding content dynamically
document.querySelector('.jarallax').innerHTML += '<p>New content</p>';

// Force recalculation
jarallax(document.querySelector('.jarallax'), 'onResize');
jarallax(document.querySelector('.jarallax'), 'onScroll');

Visibility-Based Actions

function checkVisibility() {
  const elements = document.querySelectorAll('.jarallax');
  
  elements.forEach(element => {
    const visible = jarallax(element, 'isVisible');
    
    if (visible) {
      console.log('Element is visible:', element);
      // Trigger custom actions
    }
  });
}

window.addEventListener('scroll', checkVisibility);

Events

Events allow you to hook into different stages of the parallax lifecycle.

onInit

Called after Jarallax initialization completes.

jarallax(document.querySelectorAll('.jarallax'), {
  speed: 0.5,
  onInit: function() {
    console.log('Jarallax initialized on:', this.$item);
    console.log('Options:', this.options);
  }
});

Context and available properties

Inside event callbacks, this refers to the Jarallax instance with access to:

this.$item - The parallax container element
this.options - Current configuration options
this.image - Image data object
this.image.$container - The parallax image container
this.image.$item - The image element
this.$video - Video element (if using video extension)

onDestroy

Called after the Jarallax instance is destroyed.

jarallax(document.querySelectorAll('.jarallax'), {
  speed: 0.5,
  onDestroy: function() {
    console.log('Jarallax destroyed on:', this.$item);
  }
});

onCoverImage

Called after the parallax image is covered/fitted to the container.

jarallax(document.querySelectorAll('.jarallax'), {
  speed: 0.5,
  onCoverImage: function() {
    console.log('Image covered');
  }
});

This event is triggered during initialization and whenever the container is resized.

onScroll

Called continuously during scrolling with detailed calculation data.

jarallax(document.querySelectorAll('.jarallax'), {
  speed: 0.5,
  onScroll: function(calculations) {
    console.log('Scroll calculations:', calculations);
  }
});

The onScroll event fires frequently during scrolling. Avoid heavy computations in this callback to maintain smooth performance.

onScroll Event Calculations

The onScroll event provides detailed information about the parallax element’s position and visibility.

Calculation Object

jarallax(document.querySelectorAll('.jarallax'), {
  onScroll: function(calculations) {
    console.log(calculations);
  }
});

Output structure:

{
  // Element's bounding rectangle
  section: DOMRect,

  // Distance from viewport top to element top (when element is below viewport)
  beforeTop: float,

  // Distance of visible top portion
  beforeTopEnd: float,

  // Distance scrolled past the top of element
  afterTop: float,

  // Distance from element bottom to viewport bottom (when element is above viewport bottom)
  beforeBottom: float,

  // Distance of visible bottom portion
  beforeBottomEnd: float,

  // Distance element bottom is above viewport top
  afterBottom: float,

  // Percentage of element visible (0 to 1)
  visiblePercent: float,

  // Position relative to viewport center (-1 to 1)
  // -1: element top is at viewport center
  //  0: element center is at viewport center
  //  1: element bottom is at viewport center
  fromViewportCenter: float
}

Calculation Properties Explained

visiblePercent

Represents how much of the element is visible in the viewport.

1.0: Fully visible
0.5: Half visible
0.0: Not visible

jarallax(document.querySelectorAll('.jarallax'), {
  onScroll: function(calc) {
    if (calc.visiblePercent > 0.8) {
      console.log('Element is mostly visible');
    }
  }
});

fromViewportCenter

Position relative to the viewport center, ranging from -1 to 1.

-1: Top of element is at viewport center
0: Center of element is at viewport center
1: Bottom of element is at viewport center

jarallax(document.querySelectorAll('.jarallax'), {
  onScroll: function(calc) {
    if (Math.abs(calc.fromViewportCenter) < 0.1) {
      console.log('Element is centered in viewport');
    }
  }
});

section (rect)

The element’s DOMRect object containing position and dimensions:

jarallax(document.querySelectorAll('.jarallax'), {
  onScroll: function(calc) {
    console.log('Top:', calc.section.top);
    console.log('Left:', calc.section.left);
    console.log('Width:', calc.section.width);
    console.log('Height:', calc.section.height);
  }
});

Practical onScroll Examples

Progress Indicator
Trigger Animation
Custom Parallax Math
Visibility Logging

jarallax(document.querySelectorAll('.jarallax'), {
  onScroll: function(calc) {
    // Calculate scroll progress through element
    const progress = 1 - calc.visiblePercent;
    const progressBar = this.$item.querySelector('.progress-bar');
    
    if (progressBar) {
      progressBar.style.width = (progress * 100) + '%';
    }
  }
});

jarallax(document.querySelectorAll('.jarallax'), {
  onScroll: function(calc) {
    // Trigger animation when element is centered
    if (Math.abs(calc.fromViewportCenter) < 0.1) {
      this.$item.classList.add('animate');
    }
  }
});

jarallax(document.querySelectorAll('.jarallax'), {
  onScroll: function(calc) {
    // Apply custom transformation based on scroll
    const customElement = this.$item.querySelector('.custom-element');
    
    if (customElement) {
      const rotation = calc.fromViewportCenter * 45; // Rotate ±45deg
      customElement.style.transform = `rotate(${rotation}deg)`;
    }
  }
});

jarallax(document.querySelectorAll('.jarallax'), {
  onScroll: function(calc) {
    // Log when element becomes fully visible
    if (calc.visiblePercent === 1 && !this.loggedVisible) {
      console.log('Element fully visible');
      this.loggedVisible = true;
    }
    
    if (calc.visiblePercent < 1) {
      this.loggedVisible = false;
    }
  }
});

Video Extension Events

When using the video extension, additional events are available.

onVideoInsert

Called when the video element is inserted into the DOM.

import { jarallax, jarallaxVideo } from 'jarallax';
jarallaxVideo();

jarallax(document.querySelectorAll('.jarallax'), {
  videoSrc: 'https://www.youtube.com/watch?v=ab0TSkLe-E0',
  onVideoInsert: function() {
    console.log('Video element:', this.$video);
    console.log('Video type:', this.video.type);
    
    // Add custom attributes or event listeners
    this.$video.setAttribute('data-custom', 'value');
  }
});

Access the video element via this.$video in the callback.

onVideoWorkerInit

Called when the VideoWorker instance is initialized.

jarallax(document.querySelectorAll('.jarallax'), {
  videoSrc: 'https://www.youtube.com/watch?v=ab0TSkLe-E0',
  onVideoWorkerInit: function(videoWorker) {
    console.log('VideoWorker instance:', videoWorker);
    
    // Access VideoWorker API
    videoWorker.on('ready', function() {
      console.log('Video is ready to play');
    });
    
    videoWorker.on('play', function() {
      console.log('Video started playing');
    });
    
    videoWorker.on('pause', function() {
      console.log('Video paused');
    });
  }
});

VideoWorker events

The VideoWorker instance provides these events:

ready - Video is loaded and ready to play
started - Video has started playing
play - Video play event
pause - Video pause event
ended - Video has ended
error - Video loading or playback error

These are handled internally by Jarallax, but you can add additional listeners in onVideoWorkerInit.

Complete API Example

Here’s a comprehensive example using methods and events:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Jarallax API Example</title>
    
    <link href="https://cdn.jsdelivr.net/npm/jarallax@2/dist/jarallax.min.css" rel="stylesheet">
    
    <style>
      .jarallax {
        position: relative;
        min-height: 100vh;
        display: flex;
        align-items: center;
        justify-content: center;
      }
      
      .controls {
        position: fixed;
        top: 20px;
        right: 20px;
        z-index: 1000;
        background: white;
        padding: 1rem;
        border-radius: 8px;
        box-shadow: 0 2px 10px rgba(0,0,0,0.1);
      }
      
      button {
        display: block;
        width: 100%;
        margin: 0.5rem 0;
        padding: 0.5rem 1rem;
        cursor: pointer;
      }
      
      .info {
        margin-top: 1rem;
        font-size: 0.9rem;
      }
    </style>
  </head>
  <body>
    <div class="controls">
      <h3>Controls</h3>
      <button onclick="checkVisibility()">Check Visibility</button>
      <button onclick="triggerResize()">Trigger Resize</button>
      <button onclick="triggerScroll()">Trigger Scroll</button>
      <button onclick="destroyParallax()">Destroy Parallax</button>
      <button onclick="reinitParallax()">Reinitialize</button>
      <div class="info" id="info">Ready</div>
    </div>

    <div class="jarallax" id="parallax1">
      <img class="jarallax-img" src="https://jarallax.nkdev.info/images/image1.jpg" alt="">
      <h1 style="position: relative; z-index: 1; color: white;">Scroll Down</h1>
    </div>

    <div style="height: 100vh;"></div>

    <script src="https://cdn.jsdelivr.net/npm/jarallax@2/dist/jarallax.min.js"></script>
    
    <script>
      let initialized = false;
      
      function initJarallax() {
        jarallax(document.getElementById('parallax1'), {
          speed: 0.5,
          onInit: function() {
            console.log('Jarallax initialized');
            updateInfo('Initialized');
            initialized = true;
          },
          onDestroy: function() {
            console.log('Jarallax destroyed');
            updateInfo('Destroyed');
            initialized = false;
          },
          onCoverImage: function() {
            console.log('Image covered');
          },
          onScroll: function(calc) {
            const percent = (calc.visiblePercent * 100).toFixed(2);
            updateInfo(`Visible: ${percent}%`);
          }
        });
      }
      
      function checkVisibility() {
        const visible = jarallax(document.getElementById('parallax1'), 'isVisible');
        updateInfo(`Visible: ${visible}`);
        alert(`Element is ${visible ? 'visible' : 'not visible'}`);
      }
      
      function triggerResize() {
        jarallax(document.getElementById('parallax1'), 'onResize');
        updateInfo('Resize triggered');
      }
      
      function triggerScroll() {
        jarallax(document.getElementById('parallax1'), 'onScroll');
        updateInfo('Scroll triggered');
      }
      
      function destroyParallax() {
        if (initialized) {
          jarallax(document.getElementById('parallax1'), 'destroy');
        }
      }
      
      function reinitParallax() {
        if (!initialized) {
          initJarallax();
        }
      }
      
      function updateInfo(text) {
        document.getElementById('info').textContent = text;
      }
      
      // Initialize on load
      initJarallax();
    </script>
  </body>
</html>

TypeScript Support

Jarallax includes TypeScript definitions. Here’s how to use them:

import { jarallax, JarallaxOptions, JarallaxOnScrollCalculations } from 'jarallax';

const options: JarallaxOptions = {
  speed: 0.5,
  type: 'scroll',
  onScroll: (calculations: JarallaxOnScrollCalculations) => {
    console.log('Visible percent:', calculations.visiblePercent);
  }
};

jarallax(document.querySelectorAll('.jarallax'), options);

// Methods are also typed
const isVisible: boolean = jarallax(
  document.querySelector('.jarallax'),
  'isVisible'
);

Best Practices

Use events for initialization tasks

Perform setup work in onInit to ensure Jarallax is fully ready:

jarallax(document.querySelectorAll('.jarallax'), {
  onInit: function() {
    // Safe to access parallax properties
    this.$item.classList.add('ready');
  }
});

Clean up in onDestroy

Remove event listeners and custom elements in onDestroy:

jarallax(document.querySelectorAll('.jarallax'), {
  onDestroy: function() {
    // Clean up custom event listeners
    this.$item.removeEventListener('custom', handler);
  }
});

Throttle onScroll callbacks

Limit heavy operations in onScroll to maintain performance:

let lastUpdate = 0;

jarallax(document.querySelectorAll('.jarallax'), {
  onScroll: function(calc) {
    const now = Date.now();
    if (now - lastUpdate > 100) { // Throttle to 10fps
      // Perform heavy operation
      lastUpdate = now;
    }
  }
});

Get Started

Guides

Examples

Events and Methods

Methods

destroy

isVisible

onResize

onScroll

Method Examples

Conditional Destroy

Dynamic Content Loading

Visibility-Based Actions

Events

onInit

onDestroy

onCoverImage

onScroll

onScroll Event Calculations

Calculation Object

Calculation Properties Explained

Practical onScroll Examples

Video Extension Events

onVideoInsert

onVideoWorkerInit

Complete API Example

TypeScript Support

Best Practices

Next Steps

Basic Usage

Advanced Options

Build docs developers (and LLMs) love

Get Started

Guides

Examples

​Methods

​destroy

​isVisible

​onResize

​onScroll

​Method Examples

​Conditional Destroy

​Dynamic Content Loading

​Visibility-Based Actions

​Events

​onInit

​onDestroy

​onCoverImage

​onScroll

​onScroll Event Calculations

​Calculation Object

​Calculation Properties Explained

​Practical onScroll Examples

​Video Extension Events

​onVideoInsert

​onVideoWorkerInit

​Complete API Example

​TypeScript Support

​Best Practices

​Next Steps

Basic Usage

Advanced Options

Build docs developers (and LLMs) love

Methods

destroy

isVisible

onResize

onScroll

Method Examples

Conditional Destroy

Dynamic Content Loading

Visibility-Based Actions

Events

onInit

onDestroy

onCoverImage

onScroll

onScroll Event Calculations

Calculation Object

Calculation Properties Explained

Practical onScroll Examples

Video Extension Events

onVideoInsert

onVideoWorkerInit

Complete API Example

TypeScript Support

Best Practices

Next Steps