Parallax.js

Parallax scrolling effect — works with vanilla JS, Node, React, jQuery, or any JS environment.

Author: Abhilash Sahoo
Repository: github.com/abhilashsahoo/parallax

Install

npm install @abhilashsahoo/parallax

jQuery is optional. Install it only if you want to use the jQuery API ($.fn.parallax).

Usage

Vanilla JS / Any framework

Pass a DOM element and options. No jQuery required.

import { init, destroy } from '@abhilashsahoo/parallax';

const el = document.querySelector('.parallax-window');
init(el, { imageSrc: '/path/to/image.jpg', speed: 0.3 });

// Later: destroy(el);

React

Use a ref and useEffect:

import { useRef, useEffect } from 'react';
import { init, destroy } from '@abhilashsahoo/parallax';

function ParallaxSection({ imageSrc, speed = 0.2 }) {
  const ref = useRef(null);

  useEffect(() => {
    if (!ref.current) return;
    init(ref.current, { imageSrc, speed });
    return () => destroy(ref.current);
  }, [imageSrc, speed]);

  return <div ref={ref} className="parallax-window" style={{ minHeight: '100vh', background: 'transparent' }} />;
}

jQuery

If jQuery is present, the plugin is attached automatically:

$('.parallax-window').parallax({ imageSrc: '/path/to/image.jpg' });

Browser script tag (no build)

Include the script; jQuery is optional. Elements with data-parallax="scroll" are initialised automatically.

<script src="parallax.js"></script>
<!-- Optional: <script src="https://code.jquery.com/jquery-3.7.1.min.js"></script> -->

<div class="parallax-window" data-parallax="scroll" data-image-src="/path/to/image.jpg"></div>

Styling

Parallax elements must be transparent so the effect is visible. Give the container a minimum height:

.parallax-window {
  min-height: 400px;
  background: transparent;
}

Options

| Option | Type | Default | Description | |-----------------|---------|-----------|-------------| | imageSrc | string | null | Path to the parallax image. | | naturalWidth | number | auto | Image width (optional). | | naturalHeight | number | auto | Image height (optional). | | position | string | center center | Like CSS background-position. | | positionX | string | center | Horizontal position. | | positionY | string | center | Vertical position. | | speed | float | 0.2 | Parallax speed (0 = fixed, 1 = same as scroll). | | zIndex | number | -100 | z-index of the mirror element. | | bleed | number | 0 | Extra pixels to hide scroll jitter. | | iosFix | boolean | true | Static background on iOS. | | androidFix | boolean | true | Static background on Android. | | overScrollFix | boolean | false | Fix over-scroll in Safari. | | mirrorContainer | string | 'body' | Selector for the mirror container. |

Data attributes: data-image-src, data-speed, data-z-index, etc. (camelCase → kebab-case).

License

MIT © Abhilash Sahoo