Events

Event callbacks for Jarallax lifecycle and scroll interactions

Jarallax provides event callbacks that are triggered at different stages of the parallax lifecycle. These callbacks can be passed as options during initialization.

Event Callbacks

onScroll

Called continuously while the parallax is working, providing detailed scroll calculations.

onScroll?: (calculations: JarallaxOnScrollCalculations) => void

calculations · JarallaxOnScrollCalculations

An object containing scroll position calculations and viewport metrics.

JarallaxOnScrollCalculations Interface

The calculations parameter provides the following properties:

rect · object

The parallax section’s bounding client rectangle containing top, left, width, height, right, and bottom properties.

beforeTop · number

Distance in pixels before the element reaches the top of the viewport. 0 when the element top is at or past the viewport top.

Useful for: Detecting when element is about to enter from bottom.

beforeTopEnd · number

Distance in pixels before the element completely passes the top of the viewport. 0 when element has completely scrolled past the top.

Useful for: Detecting when element is fully visible or has passed the top.

afterTop · number

Distance in pixels after the element top has passed the viewport top. 0 when element hasn’t reached the top yet.

Useful for: Measuring how far the element has scrolled into view from the top.

beforeBottom · number

Distance in pixels before the element top reaches the bottom of the viewport. 0 when element top is at or past the viewport bottom.

Useful for: Detecting when element is entering from the bottom.

beforeBottomEnd · number

Distance in pixels before the element bottom passes the viewport bottom. 0 when element has completely exited from the bottom.

Useful for: Detecting when element is about to completely leave viewport.

afterBottom · number

Distance in pixels after the element bottom has passed above the viewport bottom. 0 when element is still visible.

Useful for: Measuring how far the element has scrolled out of view.

visiblePercent · number

Percentage of the element that is visible in the viewport, ranging from 0 to 1.

• 0: Element is completely out of view
• 0.5: Element is 50% visible
• 1: Element is fully visible in the viewport

Useful for: Triggering animations based on visibility, calculating opacity, or implementing scroll-based progress indicators.

fromViewportCenter · number

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

• -1: Element is at the bottom of the viewport
• 0: Element center is aligned with viewport center
• 1: Element is at the top of the viewport

Useful for: Center-based parallax effects or symmetrical animations.

Usage Example

import { jarallax } from 'jarallax';

jarallax(document.querySelectorAll('.jarallax'), {
  speed: 0.5,
  onScroll: function(calculations) {
    console.log('Visible percent:', calculations.visiblePercent);
    console.log('From viewport center:', calculations.fromViewportCenter);
    
    // Apply custom effects based on visibility
    if (calculations.visiblePercent > 0.5) {
      this.$item.classList.add('half-visible');
    }
    
    // Custom opacity based on position
    const opacity = Math.abs(calculations.fromViewportCenter);
    this.$item.style.opacity = 1 - opacity;
  }
});

Calculations Visualization

// Example output when element is partially visible
{
  section: DOMRect {
    top: 200,
    left: 0,
    width: 1200,
    height: 600,
    right: 1200,
    bottom: 800
  },
  beforeTop: 200,
  beforeTopEnd: 800,
  afterTop: 0,
  beforeBottom: 0,
  beforeBottomEnd: 400,
  afterBottom: 0,
  visiblePercent: 0.67,
  fromViewportCenter: 0.25
}

The onScroll callback is performance-optimized and only fires when the element is in or near the viewport. It does not fire continuously when the element is completely out of view.

onInit

Called once after Jarallax initialization is complete.

onInit?: () => void

This event fires after:

• The parallax container is created
• The image is positioned
• Initial size and scroll calculations are complete
• The element is ready for parallax effects

Usage Example

jarallax(document.querySelectorAll('.jarallax'), {
  speed: 0.5,
  onInit: function() {
    console.log('Jarallax initialized');
    console.log('Element:', this.$item);
    console.log('Image container:', this.image.$container);
    
    // Add custom classes or trigger animations
    this.$item.classList.add('jarallax-ready');
    
    // Access instance properties
    console.log('Speed:', this.options.speed);
    console.log('Type:', this.options.type);
  }
});

Inside the callback, this refers to the Jarallax instance, giving you access to instance properties like this.$item, this.image, and this.options.

onDestroy

Called after the Jarallax instance has been destroyed.

onDestroy?: () => void

This event fires after:

• The parallax container is removed
• Original element styles are restored
• Event listeners and observers are cleaned up
• The instance is deleted from the element

Usage Example

jarallax(document.querySelectorAll('.jarallax'), {
  speed: 0.5,
  onDestroy: function() {
    console.log('Jarallax destroyed');
    console.log('Element:', this.$item);
    
    // Clean up custom modifications
    this.$item.classList.remove('jarallax-ready');
    
    // Remove custom event listeners
    // Perform cleanup tasks
  }
});

// Later, destroy the instance
jarallax(document.querySelectorAll('.jarallax'), 'destroy');

onCoverImage

Called after the parallax image is sized and positioned to cover the container.

onCoverImage?: () => void

This event fires:

• During initialization after the image is first sized
• Every time the image is resized (e.g., on window resize)
• When onResize method is called

Usage Example

jarallax(document.querySelectorAll('.jarallax'), {
  speed: 0.5,
  onCoverImage: function() {
    console.log('Image covered');
    console.log('Image element:', this.image.$item);
    console.log('Container:', this.image.$container);
    
    // Access image dimensions
    const imageHeight = this.image.$item.offsetHeight;
    const containerHeight = this.image.$container.offsetHeight;
    
    console.log('Image height:', imageHeight);
    console.log('Container height:', containerHeight);
  }
});

This callback is useful for debugging image sizing issues or implementing custom image positioning logic.

Complete Example

Here’s a complete example using all event callbacks:

import { jarallax } from 'jarallax';

jarallax(document.querySelectorAll('.jarallax'), {
  speed: 0.5,
  type: 'scroll',
  
  onInit: function() {
    console.log('✓ Jarallax initialized');
    this.$item.classList.add('parallax-ready');
    
    // Dispatch custom event
    this.$item.dispatchEvent(new CustomEvent('jarallax:ready'));
  },
  
  onScroll: function(calc) {
    // Update progress indicator
    const progress = calc.visiblePercent * 100;
    const progressBar = this.$item.querySelector('.progress');
    if (progressBar) {
      progressBar.style.width = `${progress}%`;
    }
    
    // Trigger waypoint when 50% visible
    if (calc.visiblePercent >= 0.5 && !this.waypointTriggered) {
      this.waypointTriggered = true;
      this.$item.classList.add('waypoint-reached');
    }
  },
  
  onCoverImage: function() {
    console.log('✓ Image covered and positioned');
  },
  
  onDestroy: function() {
    console.log('✓ Jarallax destroyed');
    this.$item.classList.remove('parallax-ready', 'waypoint-reached');
    
    // Dispatch custom event
    this.$item.dispatchEvent(new CustomEvent('jarallax:destroyed'));
  }
});

Event Execution Order

During initialization:

1. onInit - Fires once after setup is complete
2. onCoverImage - Fires after initial image sizing
3. onScroll - Fires for initial scroll position

During normal operation:

• onScroll - Fires on every scroll event (when element is in/near viewport)
• onCoverImage - Fires on window resize

During destruction:

• onDestroy - Fires once when instance is destroyed

Context (this)

Inside all event callbacks, this refers to the Jarallax instance. You have access to:

• this.$item - The main parallax element
• this.image - Image-related properties and elements
• this.image.$container - The parallax container element
• this.image.$item - The parallax image element
• this.options - The configuration options
• this.parallaxScrollDistance - Calculated scroll distance for the parallax effect

If you need to access the original element context, store a reference before initialization.