This is now a React library, Vanilla JS is still availableRead more

simpleParallax.js

simpleParallax.js

Easy Parallax Effect for React & JavaScript

simpleParallax.js is a lightweight and easy-to-use JS & React library that adds parallax animations to any image.
While other plugins can be complex, simpleParallax.js is notable for its simplicity and impressive visual effects. The parallax effect is applied directly to image tags, eliminating the need for background images. Any image can be used.
Give it a try!

hero

Installation

Install the package via npm or yarn:

// npm
npm install simple-parallax-js

// yarn
yarn add simple-parallax-js

Import it:

import SimpleParallax from "simple-parallax-js";
import SimpleParallax from "simple-parallax-js/vanilla";

Initialization

Simply add the following JavaScript code:

import SimpleParallax from "simple-parallax-js";

const Component = () => (
  <SimpleParallax>
    <img src="image.jpg" alt="image" />
  </SimpleParallax>
)
import SimpleParallax from "simple-parallax-js/";
import Image from "next/image";

const Component = () => (
  <SimpleParallax>
    <Image src="image.jpg" alt="image" width={1024} height={1920} />
  </SimpleParallax>
)
var image = document.getElementsByClassName('thumbnail');
new simpleParallax(image);

//You can also choose to apply the parallax on multiple images:

var images = document.querySelectorAll('img');
new simpleParallax(images);

Settings

nametypedefaulthint
orientationStringupup - right - down - left - up left - up right - down left - left right
scaleNumber1.4need to be above 1.0
overflowBooleanfalse
delayNumber0.4the delay is in second
transitionString'cubic-bezier(0,0,0,1)'any CSS transition
maxTransitionNumber0it should be a percentage between 1 and 99
srcStringnullVanilla version only
customContainerString or NodenullVanilla version only
customWrapperStringnullVanilla version only
  • orientation

    Stringsee example

    This is the orientation (or direction) of the parallax effect. Choose up and when scrolling down, the image will translate from the bottom to the top (so the image will translate up). When scrolling up, the image will translate from the top to the bottom. Same logic applies for all other orientations (right, down, left, up left, up right, down left, or down right). When 2 directions are combined (for example down right), the image will translate diagonally.

  • scale

    Numbersee example

    The higher the scale is set, the more visible the parallax effect will be. In return, the image will lose in quality. To reduce the lossless effect, if the scale is set at 1.5 and your image is 500px width, do the simple math 500 * 1.5 = 750. So you can choose a 750px image to replace your 500px one and don't see any quality leak. More information is available if you read the case study here.

  • overflow

    Booleansee example

    By default, the image is scaled to apply a parallax effect without any overflow on the layout - you can check the case study to have a better understanding. When overflow is set to true, the image will translate out of its natural flow (so it may overlap with your content).

  • delay

    Numbersee example

    When a delay is set, the translation of the image will continue during that delay when the user stops scrolling. That gives a very nice effect. The delay is in second.

  • transition

    Stringsee example

    The transition setting works closely with the delay setting. This setting will add any CSS transition to the delay setting. For example, you can use ease or ease-in-out.

  • maxTransition

    Numbersee example

    The maxTransition setting should be used to stop the parallax animation after a given percentage. By default, it translates from 0% to 100% of the user viewport. You can change it here to any percentage you want.

  • src

    Vanilla version onlyString

    This is the source of the image. It can be a local path or a URL.

  • customContainer

    Vanilla version onlyString or Node

    By default, the parallax calculation is done with the body scroll percentage. In some cases, the images may be in a container that has its own scroll area, so to have an accurate calculation, the custom container should be set.

  • customWrapper

    Vanilla version onlyString

    In some cases, you want to use your own wrapper instead of the one created by the plugin. If you specify your custom wrapper, the plugin will add the simpleParallax class along with an overflow: hidden style.

Methods

Refresh a simpleParallax instance (to recalculate all the positions) :Vanilla version only

var images = document.querySelectorAll('img');
var instance = new simpleParallax(images);
instance.destroy();

Destroy a simpleParallax instance Vanilla version only

var images = document.querySelectorAll('img');
var instance = new simpleParallax(images);
instance.destroy();

Examples

  • Basic config

    Basic config
    import SimpleParallax from "simple-parallax-js";
    
    const Component = () => (
      <SimpleParallax>
        <img src={"thumbnail.jpg"} alt={"image"} />
      </SimpleParallax>
    )
    import SimpleParallax from "simple-parallax-js/vanilla";
    
    var image = document.getElementsByClassName('thumbnail');
    new simpleParallax(image);
  • with a different direction

    with a different direction
    import SimpleParallax from "simple-parallax-js";
    
    const Component = () => (
      <SimpleParallax orientation="right">
        <img src={"thumbnail.jpg"} alt={"image"} />
      </SimpleParallax>
    )
    import SimpleParallax from "simple-parallax-js/vanilla";
    
    var image = document.getElementsByClassName('thumbnail');
    new simpleParallax(image, {
        orientation: 'right'
    });
  • with a higher scale

    with a higher scale
    import SimpleParallax from "simple-parallax-js";
    
    const Component = () => (
      <SimpleParallax scale={1.7}>
        <img src={"thumbnail.jpg"} alt={"image"} />
      </SimpleParallax>
    )
    import SimpleParallax from "simple-parallax-js/vanilla";
    
    var image = document.getElementsByClassName('thumbnail');
    new simpleParallax(image, {
        scale: 1.7
    });
  • with overflow

    with overflow
    import SimpleParallax from "simple-parallax-js";
    
    const Component = () => (
      <SimpleParallax overflow>
        <img src={"thumbnail.jpg"} alt={"image"} />
      </SimpleParallax>
    )
    import SimpleParallax from "simple-parallax-js/vanilla";
    
    var image = document.getElementsByClassName('thumbnail');
    new simpleParallax(image, {
        overflow: true
    });
  • with delay and transition

    with delay and transition
    import SimpleParallax from "simple-parallax-js";
    
    const Component = () => (
      <SimpleParallax delay={1} transition="cubic-bezier(0,0,0,1)">
        <img src={"thumbnail.jpg"} alt={"image"} />
      </SimpleParallax>
    )
    import SimpleParallax from "simple-parallax-js/vanilla";
    
    var image = document.getElementsByClassName('thumbnail');
    new simpleParallax(image, {
        delay: 1,
        scale: 1.5,
        transition: 'cubic-bezier(0,0,0,1)'
    });
  • with maxTransition

    with maxTransition
    import SimpleParallax from "simple-parallax-js";
    
    const Component = () => (
      <SimpleParallax maxTransition={40}>
        <img src={"thumbnail.jpg"} alt={"image"} />
      </SimpleParallax>
    )
    import SimpleParallax from "simple-parallax-js/vanilla";
    
    var image = document.getElementsByClassName('thumbnail');
    new simpleParallax(image, {
        maxTransition: 40
    });

Support the project

If you like simpleParallax.js, please consider supporting the project by giving it a star on GitHub.