Advanced Options

Jarallax offers advanced configuration options to create unique parallax effects and optimize performance across devices.

Parallax Types

Jarallax supports multiple parallax effect types through the type option.

scroll (Default)

Standard parallax scrolling effect where the background moves at a different speed than the content.

jarallax(document.querySelectorAll('.jarallax'), {
  type: 'scroll', // Default
  speed: 0.5
});

This is the most common parallax effect. The background scrolls slower than the page scroll.

scale

Scales (zooms) the image based on scroll position instead of translating it.

jarallax(document.querySelectorAll('.jarallax'), {
  type: 'scale',
  speed: 0.5
});

Positive Speed
Negative Speed

jarallax(document.querySelectorAll('.jarallax'), {
  type: 'scale',
  speed: 0.5 // Zooms in as you scroll
});

The image starts zoomed out and scales up as you scroll through it.

jarallax(document.querySelectorAll('.jarallax'), {
  type: 'scale',
  speed: -0.5 // Zooms out as you scroll
});

The image starts zoomed in and scales down as you scroll through it.

opacity

Fades the image in and out based on its visibility in the viewport.

jarallax(document.querySelectorAll('.jarallax'), {
  type: 'opacity',
  speed: 0.5
});

The speed option affects how the opacity changes. The image opacity is calculated based on how much of the element is visible in the viewport.

scroll-opacity

Combines the scroll effect with opacity changes.

jarallax(document.querySelectorAll('.jarallax'), {
  type: 'scroll-opacity',
  speed: 0.5
});

This creates a more dynamic effect where the background both moves and fades simultaneously.

scale-opacity

Combines the scale effect with opacity changes.

jarallax(document.querySelectorAll('.jarallax'), {
  type: 'scale-opacity',
  speed: 0.5
});

Type Comparison

jarallax(document.querySelectorAll('.jarallax'), {
  type: 'scroll',
  speed: 0.5
});

Speed Configuration

The speed option controls the intensity of the parallax effect. It accepts values from -1.0 to 2.0.

Understanding Speed Values

// Speed is constrained between -1.0 and 2.0
self.options.speed = Math.min(2, Math.max(-1, parseFloat(self.options.speed)));

0: Background is completely fixed (no movement)
0.5 (default): Standard parallax effect
1.0: Background moves at the same speed as scrolling (no parallax)
-1.0 to 0: Reverse parallax (background moves opposite direction)
0 to 1.0: Slower than scroll (classic parallax)
1.0 to 2.0: Faster than scroll

Speed Examples

Slow Parallax
Fast Parallax
Fixed Background
Reverse Parallax

jarallax(document.querySelectorAll('.jarallax'), {
  speed: 0.2 // Subtle effect
});

jarallax(document.querySelectorAll('.jarallax'), {
  speed: 0.8 // More dramatic effect
});

jarallax(document.querySelectorAll('.jarallax'), {
  speed: 0 // No movement
});

jarallax(document.querySelectorAll('.jarallax'), {
  speed: -0.5 // Moves in opposite direction
});

Mobile Device Detection

Jarallax provides flexible options for disabling parallax on mobile devices to improve performance.

Using Regular Expressions

jarallax(document.querySelectorAll('.jarallax'), {
  disableParallax: /iPad|iPhone|iPod|Android/
});

Using Functions

jarallax(document.querySelectorAll('.jarallax'), {
  disableParallax: function() {
    return /iPad|iPhone|iPod|Android/.test(navigator.userAgent);
  }
});

Custom Detection Logic

jarallax(document.querySelectorAll('.jarallax'), {
  disableParallax: function() {
    // Disable on small screens
    return window.innerWidth < 768;
  }
});

When parallax is disabled, the image will be displayed as a standard background without the parallax effect.

Disable Video on Mobile

Separately control video background loading on mobile:

jarallax(document.querySelectorAll('.jarallax'), {
  videoSrc: 'https://www.youtube.com/watch?v=ab0TSkLe-E0',
  disableVideo: /iPad|iPhone|iPod|Android/,
  disableParallax: false // Keep parallax on mobile, just disable video
});

You can disable video loading while keeping the parallax effect on mobile devices for better performance.

Performance Optimization

Image Position

Jarallax automatically determines the best CSS position value (fixed or absolute) for optimal performance:

// From core.js
self.image = {
  // Position is set to 'fixed' by default for better performance
  position: 'fixed'
};

// Automatically switches to 'absolute' if parent has transforms or overflow
if (self.image.position === 'fixed') {
  const $parents = getParents(self.$item).filter((el) => {
    const styles = global.getComputedStyle(el);
    const parentTransform = styles['-webkit-transform'] || 
                           styles['-moz-transform'] || 
                           styles.transform;
    const overflowRegex = /(auto|scroll)/;

    return (
      (parentTransform && parentTransform !== 'none') ||
      overflowRegex.test(styles.overflow + styles['overflow-y'] + 
                        styles['overflow-x'])
    );
  });

  self.image.position = $parents.length ? 'absolute' : 'fixed';
}

Jarallax uses position: fixed by default for optimal performance on most browsers, including MacOS with smooth scrolling. It automatically switches to absolute if parent elements have transforms or scroll overflow.

When Position is Absolute

For opacity, scale, scale-opacity types, or when speed is 1, position is automatically set to absolute:

// From core.js
if (
  self.options.type === 'opacity' ||
  self.options.type === 'scale' ||
  self.options.type === 'scale-opacity' ||
  self.options.speed === 1
) {
  self.image.position = 'absolute';
}

Custom Viewport Element

Optimize performance by checking visibility against a custom element instead of the window:

const customViewport = document.querySelector('.custom-scroll-container');

jarallax(document.querySelectorAll('.jarallax'), {
  elementInViewport: customViewport
});

This is useful when your parallax elements are inside a scrollable container rather than the main window. See Issue #13 for details.

Video Performance Options

Enable Lazy Loading

Only load videos when they enter the viewport:

jarallax(document.querySelectorAll('.jarallax'), {
  videoSrc: 'https://www.youtube.com/watch?v=ab0TSkLe-E0',
  videoLazyLoading: true // Default
});

Play Only When Visible

Pause videos when they leave the viewport:

jarallax(document.querySelectorAll('.jarallax'), {
  videoSrc: 'https://www.youtube.com/watch?v=ab0TSkLe-E0',
  videoPlayOnlyVisible: true // Default
});

Disable on Mobile

Skip video loading on mobile devices:

jarallax(document.querySelectorAll('.jarallax'), {
  videoSrc: 'https://www.youtube.com/watch?v=ab0TSkLe-E0',
  disableVideo: /iPad|iPhone|iPod|Android/
});

Container Styling

Customize the parallax container appearance:

Custom Container Class

jarallax(document.querySelectorAll('.jarallax'), {
  containerClass: 'my-custom-parallax-container'
});

The default container class is jarallax-container.

Z-Index Control

jarallax(document.querySelectorAll('.jarallax'), {
  zIndex: -100 // Default
});

For layered effects:

// Background layer
jarallax(document.querySelectorAll('.bg-layer'), {
  zIndex: -200
});

// Middle layer
jarallax(document.querySelectorAll('.mid-layer'), {
  zIndex: -100
});

Image Options

Keep Original Image

Prevent Jarallax from moving the original image element:

jarallax(document.querySelectorAll('.jarallax'), {
  keepImg: true
});

When true, Jarallax clones the image instead of moving it. This is useful when you need to maintain the original image in the DOM for other purposes.

Image Source

Explicitly set the image source:

jarallax(document.querySelectorAll('.jarallax'), {
  imgSrc: 'path/to/image.jpg'
});

Image Element Selector

Customize the selector for finding the image element:

jarallax(document.querySelectorAll('.jarallax'), {
  imgElement: '.my-custom-image-class'
});

Default: '.jarallax-img'

Complete Advanced Example

Here’s a complete example using advanced options:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Advanced Jarallax</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;
        color: white;
        text-align: center;
      }
      
      .content {
        position: relative;
        z-index: 1;
        max-width: 800px;
        padding: 2rem;
      }
    </style>
  </head>
  <body>
    <!-- Scroll type -->
    <div class="jarallax" id="section1">
      <img class="jarallax-img" src="image1.jpg" alt="">
      <div class="content">
        <h1>Scroll Parallax</h1>
      </div>
    </div>

    <!-- Scale type -->
    <div class="jarallax" id="section2">
      <img class="jarallax-img" src="image2.jpg" alt="">
      <div class="content">
        <h1>Scale Effect</h1>
      </div>
    </div>

    <!-- Opacity type -->
    <div class="jarallax" id="section3">
      <img class="jarallax-img" src="image3.jpg" alt="">
      <div class="content">
        <h1>Opacity Fade</h1>
      </div>
    </div>

    <script src="https://cdn.jsdelivr.net/npm/jarallax@2/dist/jarallax.min.js"></script>
    
    <script>
      // Different effects for each section
      jarallax(document.getElementById('section1'), {
        type: 'scroll',
        speed: 0.2
      });

      jarallax(document.getElementById('section2'), {
        type: 'scale',
        speed: 0.5
      });

      jarallax(document.getElementById('section3'), {
        type: 'opacity',
        speed: 0.8,
        disableParallax: function() {
          return window.innerWidth < 768;
        }
      });
    </script>
  </body>
</html>

Best Practices

Mobile Performance

Use disableParallax and disableVideo on mobile devices to improve performance and reduce data usage.

Speed Selection

Keep speed between 0.2 and 0.8 for subtle, professional effects. Higher values can be disorienting.

Video Optimization

Always enable videoLazyLoading and videoPlayOnlyVisible for pages with multiple video backgrounds.

Type Selection

Use scroll for most cases, scale for dramatic reveals, and opacity for subtle fades.

Get Started

Guides

Examples

Parallax Types

scroll (Default)

scale

opacity

scroll-opacity

scale-opacity

Type Comparison

Speed Configuration

Mobile Device Detection

Using Regular Expressions

Using Functions

Custom Detection Logic

Disable Video on Mobile

Performance Optimization

Image Position

When Position is Absolute

Custom Viewport Element

Video Performance Options

Container Styling

Custom Container Class

Z-Index Control

Image Options

Keep Original Image

Image Source

Image Element Selector

Complete Advanced Example

Best Practices

Mobile Performance

Speed Selection

Video Optimization

Type Selection

Next Steps

Events & Methods

Basic Usage

Build docs developers (and LLMs) love

Get Started

Guides

Examples

​Parallax Types

​scroll (Default)

​scale

​opacity

​scroll-opacity

​scale-opacity

​Type Comparison

​Speed Configuration

​Mobile Device Detection

​Using Regular Expressions

​Using Functions

​Custom Detection Logic

​Disable Video on Mobile

​Performance Optimization

​Image Position

​When Position is Absolute

​Custom Viewport Element

​Video Performance Options

​Container Styling

​Custom Container Class

​Z-Index Control

​Image Options

​Keep Original Image

​Image Source

​Image Element Selector

​Complete Advanced Example

​Best Practices

Mobile Performance

Speed Selection

Video Optimization

Type Selection

​Next Steps

Events & Methods

Basic Usage

Build docs developers (and LLMs) love

Parallax Types

scroll (Default)

scale

opacity

scroll-opacity

scale-opacity

Type Comparison

Speed Configuration

Mobile Device Detection

Using Regular Expressions

Using Functions

Custom Detection Logic

Disable Video on Mobile

Performance Optimization

Image Position

When Position is Absolute

Custom Viewport Element

Video Performance Options

Container Styling

Custom Container Class

Z-Index Control

Image Options

Keep Original Image

Image Source

Image Element Selector

Complete Advanced Example

Best Practices

Next Steps