工具介绍
适用于现代浏览器的平行滚动
# Jarallax
Parallax scrolling for modern browsers. Supported <img> tags, background images, YouTube, Vimeo and Self-Hosted Videos.
## [Online Demo](https://jarallax.nkdev.info/)
## Table of Contents
- [WordPress Plugin](#wordpress-plugin)
- [Quick Start](#quick-start)
- [Import Jarallax](#import-jarallax)
- [ESM](#esm)
- [ESM CDN](#esm-cdn)
- [UMD](#umd)
- [UMD CDN](#umd-cdn)
- [Package Imports (Bundlers / Node)](#package-imports-bundlers--node)
- [TypeScript](#typescript)
- [React / Next.js](#react--nextjs)
- [Prepare HTML](#prepare-html)
- [Run Jarallax](#run-jarallax)
- [A. JavaScript way](#a-javascript-way)
- [B. Data attribute way](#b-data-attribute-way)
- [C. jQuery way](#c-jquery-way)
- [Background Video Usage Examples](#background-video-usage-examples)
- [A. JavaScript way](#a-javascript-way-1)
- [B. Data attribute way](#b-data-attribute-way-1)
- [Options](#options)
- [Reduced motion](#reduced-motion)
- [Disable on mobile devices](#disable-on-mobile-devices)
- [Additional options for video extension](#additional-options-for-video-extension)
- [Events](#events)
- [Additional events for video extension](#additional-events-for-video-extension)
- [onScroll event](#onscroll-event)
- [Methods](#methods)
- [Call methods example](#call-methods-example)
- [A. JavaScript way](#a-javascript-way-2)
- [B. jQuery way](#b-jquery-way)
- [For Developers](#for-developers)
- [Real Usage Examples](#real-usage-examples)
- [Credits](#credits)
## WordPress Plugin
We made WordPress plugin to easily add backgrounds for content in your blog with all Jarallax features.
Demo:
Download:
## Quick Start
There are a set of examples, which you can use as a starting point with Jarallax.
- [ES Modules](examples/es-modules)
- [React](examples/react)
- [React Hooks](examples/react-hooks)
- [JavaScript](examples/javascript)
- [Next.js App Router](examples/next)
- [Next.js App Router Advanced Usage](examples/next-advanced)
- [HTML](examples/html)
- [jQuery](examples/jquery)
## 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.
```html
```
### ESM CDN
```html
```
### UMD
Jarallax may be also used in a traditional way by including script in HTML and using library by accessing `window.jarallax`.
```html
```
### UMD CDN
```html
```
### Package Imports (Bundlers / Node)
Install Jarallax as a Node.js module using npm.
```
npm install jarallax
```
Use the package root in modern bundlers:
```javascript
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:
```javascript
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.
```ts
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('.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:
```tsx
'use client';
import {
Jarallax,
JarallaxImage,
JarallaxVideo,
} from 'jarallax/react';
export function Hero() {
return (
Jarallax React
);
}
export function VideoHero() {
return (
);
}
```
Hook API for custom markup:
```tsx
'use client';
import { useJarallax } from 'jarallax/react';
export function CustomMarkupHero() {
const ref = useJarallax({
options: {
speed: 0.4,
},
});
return (
Hook-based markup control
);
}
```
Video hook API:
```tsx
'use client';
import { useJarallaxVideo } from 'jarallax/react';
export function CustomVideoHero() {
const ref = useJarallaxVideo({
options: {
speed: 0.2,
},
videoSrc: 'https://youtu.be/mru3Q5m4lkY',
});
return ;
}
```
`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
```html
```
## Run Jarallax
Note: automatic data-attribute initialization and jQuery integration are available in UMD mode only.
### A. JavaScript way
```javascript
jarallax(document.querySelectorAll('.jarallax'), {
speed: 0.2,
});
```
### B. Data attribute way
```html
```
Note: You can use all available options as data attributes. For example: `data-speed`, `data-img-src`, `data-img-size`, etc...
### C. jQuery way
```javascript
$('.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.
```javascript
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
```javascript
import { jarallax, jarallaxVideo } from 'jarallax';
jarallaxVideo();
jarallax(document.querySelectorAll('.jarallax'), {
speed: 0.2,
videoSrc: 'https://www.youtube.com/watch?v=ab0TSkLe-E0'
});
```
```html
```
### B. Data attribute way
```html
```
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 `` tag for background, you should add `object-fit` values, else use `background-size` values.
imgPosition | string | `50% 50%` | Image position. If you use `` 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 `` 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](https://github.com/nk-o/jarallax/issues/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:
```javascript
jarallax(document.querySelectorAll('.jarallax'), {
disableParallax: /iPad|iPhone|iPod|Android/,
disableVideo: /iPad|iPhone|iPod|Android/
});
```
Or using function. Example:
```javascript
jarallax(document.querySelectorAll('.jarallax'), {
disableParallax: function () {
return /iPad|iPhone|iPod|Android/.test(navigator.userAgent);
},
disableVideo: function () {
return /iPad|iPhone|iPod|Android/.test(navigator.userAgent);
}
});
```
### Reduced motion
Nothing to configure. When the reader's system asks for reduced motion, Jarallax stops on its own: the image is still covered and positioned, it just does not move with the scroll, and background video never plays. The block always keeps something to look at:
| Background | Reduced motion shows |
| :--- | :--- |
| Image | The image, positioned as usual, not moving |
| YouTube / Vimeo | The provider thumbnail; the player iframe is never requested |
| Self-hosted, with a fallback image | That image; the video is never requested |
| Self-hosted, no fallback image | The video's own first frame, inserted paused |
The parallax side matches what `disableParallax: true` already does, so the layout is the one that path has always produced. `disableVideo` keeps meaning only what you asked for — reduced motion is decided separately, because what replaces the video depends on the provider.
A fallback image (`imgSrc`, a `.jarallax-img` element, or a CSS `background-image`) is still worth adding for a self-hosted video: it gives you control over the frame and it loads faster than the video does.
Read from `(prefers-reduced-motion: reduce)` when the instance is created; changing the system setting applies on the next page load.
### 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 | st