Jarallax

Parallax scrolling for modern browsers. Supported <img> tags, background images, YouTube, Vimeo and Self-Hosted Videos.

Online Demo

WordPress Plugin
Quick Start
Import Jarallax
Prepare HTML
Run Jarallax
Background Video Usage Examples
- A. JavaScript way
- B. Data attribute way
Options
- Disable on mobile devices
- Additional options for video extension
Events
- Additional events for video extension
- onScroll event
Methods
- Call methods example
  - A. JavaScript way
  - B. jQuery way
For Developers
Real Usage Examples
Credits

WordPress Plugin

We made WordPress plugin to easily add backgrounds for content in your blog with all Jarallax features.

Demo: https://wpbackgrounds.com/

Download: https://wordpress.org/plugins/advanced-backgrounds/

Quick Start

There are a set of examples, which you can use as a starting point with Jarallax.

Import Jarallax

Use one of the following examples to import jarallax.

ESM

We ship self-hosted ESM bundles (dist/jarallax.esm.js and dist/jarallax.esm.min.js) for browsers that support ES modules.

<!-- Jarallax CSS -->
<link href="./node_modules/jarallax/dist/jarallax.min.css" rel="stylesheet">

<!-- Jarallax JS -->
<script type="module">
  import { jarallax, jarallaxVideo } from "./node_modules/jarallax/dist/jarallax.esm.js";

  // Optional video extension
  jarallaxVideo();

  jarallax(document.querySelectorAll('.jarallax'));
</script>

ESM CDN

<!-- Jarallax CSS -->
<link href="https://cdn.jsdelivr.net/npm/jarallax@3/dist/jarallax.min.css" rel="stylesheet">

<!-- Jarallax JS -->
<script type="module">
  import { jarallax, jarallaxVideo } from "https://cdn.jsdelivr.net/npm/jarallax@3/+esm";

  // Optional video extension
  jarallaxVideo();
</script>

UMD

Jarallax may be also used in a traditional way by including script in HTML and using library by accessing window.jarallax.

<!-- Jarallax CSS -->
<link href="jarallax.min.css" rel="stylesheet">

<!-- Jarallax JS -->
<script src="jarallax.min.js"></script>

<!-- Jarallax JS: Optional video extension -->
<script src="jarallax-video.min.js"></script>

UMD CDN

<!-- Jarallax CSS -->
<link href="https://cdn.jsdelivr.net/npm/jarallax@3/dist/jarallax.min.css" rel="stylesheet">

<!-- Jarallax JS -->
<script src="https://cdn.jsdelivr.net/npm/jarallax@3/dist/jarallax.min.js"></script>

<!-- Jarallax JS: Optional video extension -->
<script src="https://cdn.jsdelivr.net/npm/jarallax@3/dist/jarallax-video.min.js"></script>

Package Imports (Bundlers / Node)

Install Jarallax as a Node.js module using npm.

npm install jarallax

Use the package root in modern bundlers:

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

// Optional video extension
jarallaxVideo();

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

The package root is safe to import in SSR and Node toolchains, but Jarallax is still a frontend-only runtime and must only be initialized once a real browser DOM exists.

The CommonJS entry point remains available for older bundlers and browser-targeted build setups:

const { jarallax, jarallaxVideo } = require('jarallax');
require('jarallax/dist/jarallax.min.css');

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

In SSR frameworks such as React or Next.js, keep the import at module scope if you want, but call jarallax() only in a client-only lifecycle or behind a typeof window !== 'undefined' guard.

TypeScript

Generated declarations are published from dist/types, while typings/index.d.ts remains as a compatibility re-export.

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

const options: JarallaxOptions = {
  speed: 0.2,
  videoSrc: 'https://www.youtube.com/watch?v=ab0TSkLe-E0',
};

jarallaxVideo();
jarallax(document.querySelectorAll<HTMLElement>('.jarallax'), options);

React / Next.js

The jarallax/react subpath keeps imports SSR-safe while delaying all DOM work until useEffect runs on the client.

The built-in React components apply the required base Jarallax styles automatically, so you do not need to import jarallax.css manually when using Jarallax, JarallaxImage, or JarallaxVideo.

Component API:

'use client';

import {
  Jarallax,
  JarallaxImage,
  JarallaxVideo,
} from 'jarallax/react';

export function Hero() {
  return (
    <Jarallax className="hero" options={{ speed: 0.4 }}>
      <JarallaxImage
        src="https://jarallax.nkdev.info/images/image-1.jpg"
        alt=""
      />
      <h1>Jarallax React</h1>
    </Jarallax>
  );
}

export function VideoHero() {
  return (
    <JarallaxVideo
      className="hero"
      options={{ speed: 0.2 }}
      videoSrc="https://youtu.be/mru3Q5m4lkY"
    />
  );
}

Hook API for custom markup:

'use client';

import { useJarallax } from 'jarallax/react';

export function CustomMarkupHero() {
  const ref = useJarallax({
    options: {
      speed: 0.4,
    },
  });

  return (
    <section ref={ref} className="jarallax hero">
      <img
        className="jarallax-img"
        src="https://jarallax.nkdev.info/images/image-2.jpg"
        alt=""
      />
      <h2>Hook-based markup control</h2>
    </section>
  );
}

Video hook API:

'use client';

import { useJarallaxVideo } from 'jarallax/react';

export function CustomVideoHero() {
  const ref = useJarallaxVideo({
    options: {
      speed: 0.2,
    },
    videoSrc: 'https://youtu.be/mru3Q5m4lkY',
  });

  return <section ref={ref} className="jarallax hero" />;
}

useJarallax and useJarallaxVideo are part of the React API when you want full control over the rendered markup.

For Next.js App Router, keep these components in files marked with 'use client';. Server rendering only outputs regular HTML, and the parallax instance is created after hydration on the client.

Prepare HTML

<!-- Background Image Parallax -->
<div class="jarallax">
  <img class="jarallax-img" src="<background_image_url_here>" alt="">
  Your content here...
</div>

<!-- Background Image Parallax with <picture> tag -->
<div class="jarallax">
  <picture class="jarallax-img">
    <source media="..." srcset="<alternative_background_image_url_here>">
    <img src="<background_image_url_here>" alt="">
  </picture>
  Your content here...
</div>

<!-- Alternate: Background Image Parallax -->
<div class="jarallax" style="background-image: url('<background_image_url_here>');">
  Your content here...
</div>

Run Jarallax

Note: automatic data-attribute initialization and jQuery integration are available in UMD mode only.

A. JavaScript way

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

B. Data attribute way

<div data-jarallax data-speed="0.2" class="jarallax">
  <img class="jarallax-img" src="<background_image_url_here>" alt="">
  Your content here...
</div>

Note: You can use all available options as data attributes. For example: data-speed, data-img-src, data-img-size, etc...

C. jQuery way

$('.jarallax').jarallax({
  speed: 0.2,
});

No conflict (only if you use jQuery)

Sometimes to prevent existing namespace collisions you may call .noConflict on the script to revert the value of.

const jarallaxPlugin = $.fn.jarallax.noConflict() // return $.fn.jarallax to previously assigned value
$.fn.newJarallax = jarallaxPlugin // give $().newJarallax the Jarallax functionality

Background Video Usage Examples

A. JavaScript way

import { jarallax, jarallaxVideo } from 'jarallax';
jarallaxVideo();

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

<div class="jarallax"></div>

B. Data attribute way

<!-- Background YouTube Parallax -->
<div class="jarallax" data-jarallax data-video-src="https://www.youtube.com/watch?v=ab0TSkLe-E0">
  Your content here...
</div>

<!-- Background Vimeo Parallax -->
<div class="jarallax" data-jarallax data-video-src="https://vimeo.com/110138539">
  Your content here...
</div>

<!-- Background Self-Hosted Video Parallax -->
<div class="jarallax" data-jarallax data-video-src="mp4:./video/local-video.mp4,webm:./video/local-video.webm,ogv:./video/local-video.ogv">
  Your content here...
</div>

Note: self-hosted videos require 1 video type only, not necessarily using all mp4, webm, and ogv. This is only needed for maximum compatibility with all browsers.

Options

Options can be passed in data attributes or in object when you initialize jarallax from script.

Name	Type	Default	Description
type	string	`scroll`	scroll, scale, opacity, scroll-opacity, scale-opacity.
speed	float	`0.5`	Parallax effect speed. Provide numbers from -1.0 to 2.0.
containerClass	string	`jarallax-container`	Container block class attribute.
imgSrc	path	`null`	Image url. By default used image from background.
imgElement	dom / selector	`.jarallax-img`	Image tag that will be used as background.
imgSize	string	`cover`	Image size. If you use `<img>` tag for background, you should add `object-fit` values, else use `background-size` values.
imgPosition	string	`50% 50%`	Image position. If you use `<img>` tag for background, you should add `object-position` values, else use `background-position` values.
imgRepeat	string	`no-repeat`	Image repeat. Supported only `background-position` values.
keepImg	boolean	`false`	Keep `<img>` tag in it's default place after Jarallax inited.
elementInViewport	dom	`null`	Use custom DOM / jQuery element to check if parallax block in viewport. More info here - Issue 13.
zIndex	number	`-100`	z-index of parallax container.
disableParallax	boolean / RegExp / function	-	Disable parallax on specific user agents (using regular expression) or with function return value. The image will be set on the background.

Disable on mobile devices

You can disable parallax effect and/or video background on mobile devices using option disableParallax and/or disableVideo.

Example:

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

Or using function. Example:

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

Additional options for video extension

Requires the video extension bundle. In package-based apps call jarallaxVideo() after importing from jarallax. In script-tag usage load dist/jarallax-video(.min).js after the core bundle.

Name	Type	Default	Description
videoClass	string	`jarallax-video`	Video frame class attribute. Will also contain the type of the video, for example `jarallax-video jarallax-video-youtube`
videoSrc	string	`null`	You can use Youtube, Vimeo or Self-Hosted videos. Also you can use data attribute `data-jarallax-video`.
videoStartTime	float	`0`	Start time in seconds when video will be started (this value will be applied also after loop).
videoEndTime	float	`0`	End time in seconds when video will be ended.
videoLoop	boolean	`true`	Loop video to play infinitely.
videoPlayOnlyVisible	boolean	`true`	Play video only when it is visible on the screen.
videoLazyLoading	boolean	`true`	Preload videos only when it is visible on the screen.
disableVideo	boolean / RegExp / function	-	Disable video load on specific user agents (using regular expression) or with function return value. The image will be set on the background.

Events

Events used the same way as Options.

Name	Description
onScroll	Called when parallax working. Use first argument with calculations. More info see below.
onInit	Called after init end.
onDestroy	Called after destroy.
onCoverImage	Called after cover image.

Additional events for video extension

Requires the video extension bundle. In package-based apps call jarallaxVideo() after importing from jarallax. In script-tag usage load dist/jarallax-video(.min).js after the core bundle.

Name	Description
onVideoInsert	Called right after video is inserted in the parallax block. Video can be accessed by `this.$video`
onVideoWorkerInit	Called after VideoWorker script initialized. Available parameter with videoWorkerObject.

onScroll event

jarallax(document.querySelectorAll('.jarallax'), {
  onScroll: function(calculations) {
    console.log(calculations);
  }
});

Console Result:

{
  // parallax section client rect (top, left, width, height)
  rect            : object,

  // see image below for more info
  beforeTop       : float,
  beforeTopEnd    : float,
  afterTop        : float,
  beforeBottom    : float,
  beforeBottomEnd : float,
  afterBottom     : float,

  // percent of visible part of section (from 0 to 1)
  visiblePercent  : float,

  // percent of block position relative to center of viewport from -1 to 1
  fromViewportCenter: float
}

Calculations example:

Methods

Name	Result	Description
destroy	-	Destroy Jarallax and set block as it was before plugin init.
isVisible	boolean	Check if parallax block is in viewport.
onResize	-	Fit image and clip parallax container. Called on window resize and load.
onScroll	-	Calculate parallax image position. Called on window scroll.

Call methods example

A. JavaScript way

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

B. jQuery way

$('.jarallax').jarallax('destroy');

For Developers

Installation

Run npm install in the repository root

Core workflows

npm run dev to run build and start local server with files watcher
npm run build to build all distributable bundles and declarations
npm run typecheck to type-check source and Vitest coverage

Quality checks

npm run lint to run Biome lint checks
npm run lint:fix to apply Biome lint fixes
npm run format:check to verify formatting
npm run format to apply formatting

Test

npm run test for interactive Vitest
npm run test:run for a single CI-style test run
npm run test:coverage for coverage output
npm run test:artifacts to validate the published package contract

Examples in this repository

The HTML, JavaScript, jQuery, and ES modules examples under examples/ use CDN assets so they can be opened without a local package build
In examples/es-modules, run npm install and npm run dev to serve the example through BrowserSync while keeping CDN imports
In examples/next, run npm install and npm run dev to test the published package shape through Next.js
In examples/next-advanced, run npm install and npm run dev to test dynamic block updates against the published package shape

Real Usage Examples

Credits

Images https://unsplash.com/
Videos https://videos.pexels.com/

Name		Name	Last commit message	Last commit date
Latest commit History 455 Commits
.github		.github
.husky		.husky
.vscode		.vscode
demo		demo
dist		dist
examples		examples
src		src
tests		tests
typings		typings
.browserslistrc		.browserslistrc
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
biome.json		biome.json
lint-staged.config.js		lint-staged.config.js
package-lock.json		package-lock.json
package.json		package.json
rollup.config.mjs		rollup.config.mjs
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
tsconfig.tests.json		tsconfig.tests.json
vitest.config.mjs		vitest.config.mjs

Folders and files

Latest commit

History

Repository files navigation

Jarallax

Online Demo

Table of Contents

WordPress Plugin

Quick Start

Import Jarallax

ESM

ESM CDN

UMD

UMD CDN

Package Imports (Bundlers / Node)

TypeScript

React / Next.js

Prepare HTML

Run Jarallax

A. JavaScript way

B. Data attribute way

C. jQuery way

No conflict (only if you use jQuery)

Background Video Usage Examples

A. JavaScript way

B. Data attribute way

Options

Disable on mobile devices

Additional options for video extension

Events

Additional events for video extension

onScroll event

Methods

Call methods example

A. JavaScript way

B. jQuery way

For Developers

Installation

Core workflows

Quality checks

Test

Examples in this repository

Real Usage Examples

Credits

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages