Quick Start Guide

This guide will walk you through creating your first parallax effect with Jarallax. You’ll go from zero to a working parallax scrolling background in just a few steps.

Basic Parallax Image

The simplest way to use Jarallax is with a background image and the <img> tag.

Add the HTML structure

Create a container element with the jarallax class and an <img> element with the jarallax-img class:

<div class="jarallax" style="height: 500px;">
  <img class="jarallax-img" src="path/to/image.jpg" alt="Background" />
  <div style="position: relative; z-index: 1;">
    <h1>Your Content Here</h1>
    <p>This content appears above the parallax background.</p>
  </div>
</div>

Add a minimum height to your parallax container so it has dimensions to work with.

Initialize Jarallax

Call the jarallax function on your elements:

import { jarallax } from 'jarallax';
import 'jarallax/dist/jarallax.min.css';

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

Or with custom options:

jarallax(document.querySelectorAll('.jarallax'), {
  speed: 0.2, // Parallax speed (0.0 to 2.0)
});

See it in action

Scroll the page and watch your background move at a different speed than your content!

Alternative: CSS Background Image

You can also use CSS background images instead of <img> tags:

<div 
  class="jarallax" 
  style="background-image: url('path/to/image.jpg'); height: 500px;"
>
  <div style="position: relative; z-index: 1;">
    <h1>Your Content Here</h1>
  </div>
</div>

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

Data Attribute Initialization

When using UMD mode, Jarallax can automatically initialize elements with the data-jarallax attribute:

<!-- Automatic initialization (UMD only) -->
<div 
  data-jarallax 
  data-speed="0.2" 
  class="jarallax"
  style="height: 500px;"
>
  <img class="jarallax-img" src="path/to/image.jpg" alt="" />
</div>

With data attributes, you can configure all options directly in HTML. For example: data-speed="0.5", data-type="scale", data-img-position="0% 50%".

Complete Working Example

Here’s a full HTML page with a working parallax effect:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Jarallax Example</title>
    
    <!-- Jarallax CSS -->
    <link 
      href="https://cdn.jsdelivr.net/npm/jarallax@2/dist/jarallax.min.css" 
      rel="stylesheet" 
    />
    
    <style>
      body {
        margin: 0;
        font-family: system-ui, sans-serif;
      }
      
      .jarallax {
        position: relative;
        height: 100vh;
        display: flex;
        align-items: center;
        justify-content: center;
      }
      
      .content {
        position: relative;
        z-index: 1;
        text-align: center;
        color: white;
        padding: 2rem;
        background: rgba(0, 0, 0, 0.3);
        border-radius: 8px;
      }
      
      .section {
        padding: 4rem 2rem;
        text-align: center;
      }
    </style>
  </head>
  <body>
    <div class="section">
      <h1>Scroll Down</h1>
      <p>Watch the parallax effect in action</p>
    </div>

    <div class="jarallax">
      <img 
        class="jarallax-img" 
        src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4" 
        alt="Mountain landscape" 
      />
      <div class="content">
        <h2>Parallax Scrolling</h2>
        <p>Background moves at a different speed</p>
      </div>
    </div>

    <div class="section">
      <h2>Keep Scrolling</h2>
      <p>Notice how the background moved slower than the page</p>
    </div>

    <script type="module">
      import { jarallax } from "https://cdn.jsdelivr.net/npm/jarallax@2/+esm";
      
      jarallax(document.querySelectorAll(".jarallax"), {
        speed: 0.2,
      });
    </script>
  </body>
</html>

Video Background Example

Add a YouTube or Vimeo video as a parallax background:

Load the video extension

import { jarallax, jarallaxVideo } from 'jarallax';
import 'jarallax/dist/jarallax.min.css';

// Initialize video extension
jarallaxVideo();

Add HTML with video URL

<div class="jarallax" style="height: 600px;">
  <div style="position: relative; z-index: 1;">
    <h1>Video Background</h1>
  </div>
</div>

Initialize with videoSrc option

JavaScript
Data Attribute

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

<div 
  class="jarallax" 
  data-jarallax 
  data-video-src="https://www.youtube.com/watch?v=ab0TSkLe-E0"
  style="height: 600px;"
>
  <h1>Video Background</h1>
</div>

Supported Video Formats

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

For self-hosted videos, provide at least one format (mp4, webm, or ogv). Multiple formats ensure better browser compatibility.

Customizing Speed

The speed option controls how fast the background moves relative to scrolling:

// Slower than scrolling (subtle effect)
jarallax(element, { speed: 0.2 });

// Default speed
jarallax(element, { speed: 0.5 });

// Faster than scrolling
jarallax(element, { speed: 1.5 });

// No parallax (moves with page)
jarallax(element, { speed: 1 });

// Reverse direction
jarallax(element, { speed: -0.5 });

Speed values range from -1.0 to 2.0:

< 0: Background moves in reverse
0.0 - 0.9: Background moves slower (parallax effect)
1.0: No parallax (fixed background)
> 1.0: Background moves faster

Different Effect Types

Jarallax supports multiple effect types:

jarallax(element, {
  type: 'scroll', // Background moves at different speed
  speed: 0.5,
});

Using with Picture Element

For responsive images with different sources:

<div class="jarallax" style="height: 500px;">
  <picture class="jarallax-img">
    <source 
      media="(min-width: 1024px)" 
      srcset="desktop-image.jpg" 
    />
    <source 
      media="(min-width: 768px)" 
      srcset="tablet-image.jpg" 
    />
    <img src="mobile-image.jpg" alt="Responsive background" />
  </picture>
  <div style="position: relative; z-index: 1;">
    <h1>Responsive Parallax</h1>
  </div>
</div>

Disable on Mobile

Optionally disable parallax on mobile devices for better performance:

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

Or use a function:

jarallax(document.querySelectorAll('.jarallax'), {
  speed: 0.2,
  disableParallax: function() {
    return window.innerWidth < 768;
  },
});

Common Patterns

Hero Section

<div class="jarallax hero" style="height: 100vh;">
  <img class="jarallax-img" src="hero-bg.jpg" alt="" />
  <div class="hero-content">
    <h1>Welcome</h1>
    <p>Amazing parallax scrolling</p>
    <button>Get Started</button>
  </div>
</div>

<style>
  .hero-content {
    position: relative;
    z-index: 1;
    text-align: center;
    color: white;
    display: flex;
    flex-direction: column;
    align-items: center;
    justify-content: center;
    height: 100%;
  }
</style>

Multiple Sections

// Initialize all parallax sections at once
jarallax(document.querySelectorAll('.jarallax'), {
  speed: 0.2,
});

// Or configure each individually
jarallax(document.querySelector('.hero'), { speed: 0.2 });
jarallax(document.querySelector('.about'), { speed: 0.5, type: 'scale' });
jarallax(document.querySelector('.contact'), { speed: -0.2 });

Troubleshooting

Parallax not working

Ensure the container has a defined height
Check that CSS file is loaded
Verify jarallax function is called after DOM is ready
Check browser console for errors

Image not showing

Verify image path is correct
Check that image has loaded (Network tab)
Ensure CSS is properly loaded
Try using imgSrc option directly: jarallax(element, { imgSrc: 'path/to/image.jpg' })

Performance issues on mobile

Use the disableParallax option to disable on mobile
Reduce image file sizes
Consider using disableVideo for video backgrounds on mobile

Next Steps

Now that you have a working parallax effect, explore more advanced features:

Configuration Options

Learn about all available options and callbacks

API Reference

Explore methods and programmatic control

Video Backgrounds

Deep dive into video parallax features

Examples

Browse more example implementations

Get Started

Guides

Examples

Quick Start

Quick Start Guide

Basic Parallax Image

Alternative: CSS Background Image

Data Attribute Initialization

Complete Working Example

Video Background Example

Supported Video Formats

Customizing Speed

Different Effect Types

Using with Picture Element

Disable on Mobile

Common Patterns

Hero Section

Multiple Sections

Troubleshooting

Next Steps

Configuration Options

API Reference

Video Backgrounds

Examples

Build docs developers (and LLMs) love

Get Started

Guides

Examples

​Quick Start Guide

​Basic Parallax Image

​Alternative: CSS Background Image

​Data Attribute Initialization

​Complete Working Example

​Video Background Example

​Supported Video Formats

​Customizing Speed

​Different Effect Types

​Using with Picture Element

​Disable on Mobile

​Common Patterns

​Hero Section

​Multiple Sections

​Troubleshooting

​Next Steps

Configuration Options

API Reference

Video Backgrounds

Examples

Build docs developers (and LLMs) love

Quick Start Guide

Basic Parallax Image

Alternative: CSS Background Image

Data Attribute Initialization

Complete Working Example

Video Background Example

Supported Video Formats

Customizing Speed

Different Effect Types

Using with Picture Element

Disable on Mobile

Common Patterns

Hero Section

Multiple Sections

Troubleshooting

Next Steps