Easy Parallax Scrolling Effect In Vanilla JavaScript – parallax-vanilla

Category: Animation , Javascript | October 2, 2026
Authoralxv2016
Last UpdateOctober 2, 2026
LicenseMIT
Views4,007 views
Easy Parallax Scrolling Effect In Vanilla JavaScript – parallax-vanilla

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(), and destroy() 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-motion handling 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,
  },
})
SettingTypeDefaultDescription
container.classstringpv-containerClass used to find parallax containers.
container.heightstring | number250pxContainer height. Numbers and numeric strings use pixels. Strings can use px or vh.
block.classstringpv-blockClass used to find parallax blocks inside each container.
block.speednumber-Math.PIParallax speed and direction. Use a finite, non-zero number. Larger absolute values move less.
block.mediatypestringimageMedia type: image, video, or none. Recognized video file extensions are handled as video automatically.
block.mediapathstring | nullnullImage or video URL. A media path is required unless the block uses mediatype: 'none'.
block.mutebooleanfalseWhen true, videos stay muted and the sound button is omitted.

Data Attributes

AttributeSettingDescription
pv-heightcontainer.heightSets the height for one container. Accepts a number, a numeric string, px, or vh.
pv-speedblock.speedSets speed and direction for one block. A value of 0 falls back to the default speed.
pv-mediatypeblock.mediatypeSets image, video, or none.
pv-mediapathblock.mediapathSets the image or video URL for one block.
pv-muteblock.muteAn empty attribute or pv-mute="true" sets mute to true. pv-mute="false" sets it to false.

API Methods

MethodDescription
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

ExportDescription
initNamed export for initialization.
refreshNamed export for manual layout recalculation.
destroyNamed export for teardown.
defaultSettingsResolved default configuration object.
defaultObject containing init, refresh, and destroy.
MediaTypeTypeScript type for image, video, or none.
SettingsTypeScript type for the resolved configuration.
UserSettingsTypeScript type accepted by init(); every nested setting is optional.

CSS Classes

ClassRole
pv-containerDefault parallax container. The stylesheet applies relative positioning and hidden overflow.
pv-blockDefault parallax block. The stylesheet defines media sizing and background behavior.
audio-iconGenerated sound button for video blocks when mute is false.
muteState 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.pv exposes init, refresh, and destroy.
  • window.raf has been removed.
  • Calling init() again tears down the previous setup before rebuilding it.
  • An empty pv-mute attribute now behaves like a boolean HTML attribute and means muted.
  • The video sound control is a labelled <button>.

Alternatives & Related Resources

Changelog

v2.0.0 (10/02/2026)

  • Added ES module and CommonJS builds with TypeScript types.
  • Added refresh() and destroy().
  • Added prefers-reduced-motion handling.
  • Added automatic layout, container resize, window resize, and device rotation updates.
  • Expanded video detection to include webm, ogv, and mkv.
  • 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.

You Might Be Interested In:


Leave a Reply