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
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.
calculations parameter provides the following properties:
The parallax section’s bounding client rectangle containing top, left, width, height, right, and bottom properties.
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.
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.
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.
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.
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.
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.
Percentage of the element that is visible in the viewport, ranging from 0 to 1.
0: Element is completely out of view0.5: Element is 50% visible1: Element is fully visible in the viewport
Useful for: Triggering animations based on visibility, calculating opacity, or implementing scroll-based progress indicators. Position of the element relative to the center of the viewport, ranging from -1 to 1.
-1: Element is at the bottom of the viewport0: Element center is aligned with viewport center1: 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.
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.
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
- 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:
- onInit - Fires once after setup is complete
- onCoverImage - Fires after initial image sizing
- 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 elementthis.image - Image-related properties and elementsthis.image.$container - The parallax container elementthis.image.$item - The parallax image elementthis.options - The configuration optionsthis.parallaxScrollDistance - Calculated scroll distance for the parallax effect
If you need to access the original element context, store a reference before initialization. 