Skip to content
Small, performance optimized module for parallax image backgrounds 🖼
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.


Type Name Latest commit message Commit time
Failed to load latest commit information.


A small (~1KB gzip), performance optimized module for parallax image backgrounds. Aims to be as straight forward and semantic as possible, without tricks, hacks, element clones, layout thrashing, etc.



yarn add prlx


npm install prlx --save


<script src="dist/prlx.js"></script>


Argument Required Description
item Yes Selector string for parent element
image Yes Selector string for image element inside parent



<div class="example">
  <div class="img"></div>
prlx('.example', '.img');


This plugin is intented to be used for image backgrounds. There has to be a parent element (to hide the parallax overflow), and a child element. See example above. Naturally, some styling has to be involved. There isn't any bundled CSS file or activated style through JavaScript, to give as much freedom as possible. However, these are the required style rules to work as intended:

$parallax-space: 20%; // Example, can be anything

.example {
  height: $element-height;
  overflow: hidden;
  position: relative;

  .img {
    background-image: url('image.jpg');
    height: 100% + $parallax-space;
    position: absolute; /* 1 */
    top: -($parallax-space / 2);
    width: 100%; // Example, can be anything

These are additional recommended styles rules:

.example {
  .img {
    background-position: 50%;
    background-size: cover;
    display: none; /* 2 */
    will-change: transform; /* 3 */
  1. Absolute positioning is the best option for optimal animation performance.
  2. When you load JavaScript in the footer/async/defer, it's a good idea to initially hide the image element. This will solve the (minimal) visual change of the image's position after the page is done loading.
  3. Will create a dedicated paint layer for the parallax animation.

Manual recalculation

When there are other libraries/scripts at work who influence the DOM after prlx is done calculating its values, it may be necessary to recalculate values. This can be done at any time:

const example = prlx('.example', '.img');


Browser resizing

Positions will be recalculated when the browser is resized. That means orientation changes on tablets and media queries on the element can be done safely.


As pointed out before, this plugin aims to be as performant as possible. Therefore, browsers that don't implement requestAnimationFrame are not supported.

iOS 7

iOS 7 is not supported, since DOM painting is paused during scroll events which doesn't play well with parallax scrolling.


Fallback is gracious, since the image will just be displayed normally.

You can’t perform that action at this time.