
parallax-vanilla is a dependency-free JavaScript library for parallax scrolling with images, videos, and regular HTML content.
Each paralax block can use its own speed and media settings, and the library tracks layout changes and container resizes automatically.
Features
- Parallax scrolling for images, videos, and HTML content.
- Per-container height and per-block speed settings.
- Per-element configuration through
pv-*attributes. - Automatic video detection from media file extensions.
- ES module and CommonJS builds with TypeScript types.
init(),refresh(), anddestroy()lifecycle methods.- Automatic updates after container resizes, page layout changes, window resizes, and device rotation.
- Offscreen videos pause until their container returns to the viewport.
prefers-reduced-motionhandling for motion-sensitive visitors.
How To Use It
CDN Setup
Load the required stylesheet in the document head. Load the browser build before the closing body tag.
<link rel="stylesheet" href="https://unpkg.com/parallax-vanilla@2/dist/parallax-vanilla.css" /> <script src="https://unpkg.com/parallax-vanilla@2/dist/parallax-vanilla.js"></script>
npm and Module Setup
Install the package via NPM, then import the JavaScript API and stylesheet in your project.
npm install parallax-vanilla
import { init } from 'parallax-vanilla'
import 'parallax-vanilla/parallax-vanilla.css'
init()Basic Image Parallax
Create a pv-block inside a pv-container. Set the image through pv-mediapath, and initialize the library after the markup is available.
<div class="pv-container"> <div class="pv-block" pv-mediapath="images/hero.jpg"></div> </div> <script> pv.init() </script>
Set Container Height and Parallax Speed
pv-height accepts pixel values and viewport-height values. pv-speed controls speed and direction. Negative values move the block upward as the page scrolls down.
<div class="pv-container" pv-height="50vh">
<div
class="pv-block"
pv-mediapath="images/mountains.jpg"
pv-speed="-2"
></div>
</div>Video Parallax
A media path with a recognized video extension is handled as video. Videos play inline, loop, and start muted. Leave pv-mute off when you want the built-in sound button. Use the empty pv-mute attribute to keep the video muted and omit the sound button.
<div class="pv-container" pv-height="500px">
<div
class="pv-block"
pv-mediapath="media/hero.webm"
pv-speed="-2.5"
></div>
</div>
<div class="pv-container" pv-height="500px">
<div
class="pv-block"
pv-mediapath="media/background.mp4"
pv-mute
></div>
</div>Parallax HTML Content
Set pv-mediatype="none" when the block contains regular HTML rather than an image or video.
<div class="pv-container" pv-height="50vh">
<div class="pv-block" pv-mediapath="images/leaves.jpg"></div>
<div class="pv-block" pv-mediatype="none" pv-speed="3">
<h2>Parallax heading</h2>
</div>
</div>Configuration Options
Every setting is optional. JavaScript settings apply globally, and an element-level pv-* attribute overrides the corresponding setting for that element. A custom container or block class also requires matching CSS rules.
pv.init({
container: {
class: 'pv-container',
height: '250px',
},
block: {
class: 'pv-block',
speed: -Math.PI,
mediatype: 'image',
mediapath: null,
mute: false,
},
})| Setting | Type | Default | Description |
|---|---|---|---|
container.class | string | pv-container | Class used to find parallax containers. |
container.height | string | number | 250px | Container height. Numbers and numeric strings use pixels. Strings can use px or vh. |
block.class | string | pv-block | Class used to find parallax blocks inside each container. |
block.speed | number | -Math.PI | Parallax speed and direction. Use a finite, non-zero number. Larger absolute values move less. |
block.mediatype | string | image | Media type: image, video, or none. Recognized video file extensions are handled as video automatically. |
block.mediapath | string | null | null | Image or video URL. A media path is required unless the block uses mediatype: 'none'. |
block.mute | boolean | false | When true, videos stay muted and the sound button is omitted. |
Data Attributes
| Attribute | Setting | Description |
|---|---|---|
pv-height | container.height | Sets the height for one container. Accepts a number, a numeric string, px, or vh. |
pv-speed | block.speed | Sets speed and direction for one block. A value of 0 falls back to the default speed. |
pv-mediatype | block.mediatype | Sets image, video, or none. |
pv-mediapath | block.mediapath | Sets the image or video URL for one block. |
pv-mute | block.mute | An empty attribute or pv-mute="true" sets mute to true. pv-mute="false" sets it to false. |
API Methods
| Method | Description |
|---|---|
init(settings?) | Finds current containers and blocks, applies the settings, and starts the effect. Calling it again destroys the previous setup before rebuilding it. |
refresh() | Recomputes sizes and positions for layout changes that the library did not detect automatically. |
destroy() | Stops the effect, removes generated videos and sound buttons, and restores inline styles changed by the library. |
Module Exports
| Export | Description |
|---|---|
init | Named export for initialization. |
refresh | Named export for manual layout recalculation. |
destroy | Named export for teardown. |
defaultSettings | Resolved default configuration object. |
default | Object containing init, refresh, and destroy. |
MediaType | TypeScript type for image, video, or none. |
Settings | TypeScript type for the resolved configuration. |
UserSettings | TypeScript type accepted by init(); every nested setting is optional. |
CSS Classes
| Class | Role |
|---|---|
pv-container | Default parallax container. The stylesheet applies relative positioning and hidden overflow. |
pv-block | Default parallax block. The stylesheet defines media sizing and background behavior. |
audio-icon | Generated sound button for video blocks when mute is false. |
mute | State class applied to the generated sound button while its video is muted. |
Upgrading From 1.x
- Bower installation has been removed. Use npm or a CDN build.
window.pvexposesinit,refresh, anddestroy.window.rafhas been removed.- Calling
init()again tears down the previous setup before rebuilding it. - An empty
pv-muteattribute now behaves like a boolean HTML attribute and means muted. - The video sound control is a labelled
<button>.
Alternatives & Related Resources
- 10 Best Parallax Scrolling Effects In JavaScript
- Animate Elements On Scroll With Parallax Effect – locomotive-scroll
- Parallax Scrolling Library For Mobile & Desktop – basicScroll
- Smooth Responsive Parallax Scrolling Library For The Web – Parallax-Scroller
- JavaScript & CSS Parallax
Changelog
v2.0.0 (10/02/2026)
- Added ES module and CommonJS builds with TypeScript types.
- Added
refresh()anddestroy(). - Added
prefers-reduced-motionhandling. - Added automatic layout, container resize, window resize, and device rotation updates.
- Expanded video detection to include
webm,ogv, andmkv. - Fixed decimal speeds, numeric container heights, media-path settings, video playback, and resize behavior.
v1.2.0 (07/13/2019)
- Migrated the project to TypeScript.
v1.1.3 (06/19/2018)
- Replaced the spread operation with a loop for browser compatibility.







