React Next Parallax

A Performant Customizable React Component Providing the Parallax Effect

Main Demo • Attributes Demo • Control Element Demo • Storybook

Table of Contents

• Features
• Installation
• Usage
• Attributes
• Props
• Default Values
• Events/Callbacks
• Ref
• Credits
• Author
• License

Features

• Easy to use
• Highly customizable
• Built with performance in mind
• Built from the ground up using React Hooks/TypeScript (is not a port of another library)
• Minimum amount of component re-renders
• Typed props with JSDoc descriptions
• Tested extensively using Cypress/Storybook
• Plus all of the features of react-next-tilt like:
  • Touch and Gyroscope Support
  • Two customizable glare effects (spot/line)
  • Scale on Hover/Touch
  • Shadow on Hover/Touch
  • Disable Scroll on Touch
  • Full-Page Listening
  • Control Element
  • and more

Installation

$ npm install react-next-parallax

Once the package is installed, you can import the component:

import { Parallax } from 'react-next-parallax';

Usage

1. Set up your scene (HTML/CSS)

For multi-layer images, separate each layer into an individual image and put them inside a container so that they are stacked on top of each other. (usually with a position:relative container and position:absolute images)

Simplified example using Tailwind:

<div className="relative w-[800px] h-[600px] [&>img]:absolute [&>img]:inset-0">
  <img src="image1.jpg" />
  <img src="image2.jpg" />
  <img src="image3.jpg" />
</div>

2. Add the desired data-parallax-... attribute

Add the desired attribute to the images or any other element you want the effect to be applied to. (You can check the Attributes Demo to learn more about each attribute)

<div className="relative w-[800px] h-[600px] [&>img]:absolute [&>img]:inset-0">
  <img src="image1.jpg" data-parallax-offset="-5" />
  <img src="image2.jpg" />
  <img src="image3.jpg" data-parallax-offset="5" />
</div>

3. Place your elements inside <Parallax></Parallax>

Place the elements/components you want to have the parallax effect inside <Parallax></Parallax>

Example:

<Parallax>
  <div className="relative w-[800px] h-[600px] [&>img]:absolute [&>img]:inset-0">
    <img src="image1.jpg" data-parallax-offset="-5" />
    <img src="image2.jpg" />
    <img src="image3.jpg" data-parallax-offset="5" />
  </div>
</Parallax>

4. Make the required adjustments

• You may want to change the size of the images depending on the values chosen for the data-parallax-offset so the edges are not visible when tilted to extreme angles.
• You can also change the props like animationMode and offsetMultiplier to achieve the exact effect you want.

You can use all of the props of react-next-tilt for customization as well.

Example:

<Parallax offsetMultiplier={2} scale={1.2}>
  <div className="relative w-[800px] h-[600px] [&>img]:absolute [&>img]:inset-0">
    <img src="image1.jpg" data-parallax-offset="-5" />
    <img src="image2.jpg" />
    <img src="image3.jpg" data-parallax-offset="5" />
  </div>
</Parallax>

Attributes

• All attributes are optional
• You can use multiple attributes at the same time.
• You can use transform functions at the same time as using an attribute. each attribute only overwrites its own transform function not the whole transform.
• If you want to apply animations to an element and the properties you want to animate overlap with the transform function used by the attribute, you can:
  • Use the separate properties for animation instead. (e.g. translate property instead of transform: translate() function)
  • Put the element inside a container/parent element and animate it instead.
• To reverse the animation direction of attributes that take two numbers as input, you can either swap the start and end numbers ("start;end" → "end;start") or use the animationReverse prop.
• You can change the animation mode for data-parallax-...="x;y" attributes using the animationMode prop.
• You can use the specific multiplier prop for each attribute to easily adjust the values after setting them up.
• You can check the Attributes Demo to learn more about each attribute.

Name	Description	Value Represents	Transform functions overwritten	Demo
data-parallax-offset="±number"	Moves (translates) the element based on the tilt angle. Elements with positive numbers will appear to be in the front and elements with negative numbers will appear to be in the back. Higher numbers increase the amount of movement.	Percentage of the element's size	translate() translateX() translateY() translate3d()	Offset Demo
data-parallax-opacity="start;end"	Changes the opacity of the element based on the tilt angle.	Opacity of the element	none (opacity property)	Opacity Demo
data-parallax-scale="start;end"	Changes the scale of the element based on the tilt angle.	Scale of the element	scale() scaleX() scaleY() scale3d()	Scale Demo
data-parallax-rotation="start;end"	Changes the rotation of the element based on the tilt angle.	Rotation angle of the element in degrees	rotate() rotateZ() rotate3d()	Rotation Demo
data-parallax-skew="start;end"	Changes the skew angle of the element based on the tilt angle.	Skew angle of the element in degrees	skew() skewX() skewY() skew3d()	Skew Demo

Props

All props are optional

In addition to these props, you can use:

• Any of the react-next-tilt props like scale, disableScrollOnTouch, controlElement, etc.
• Any valid HTMLDivElement props like className='', data-...='...', onMouseMove={...} etc. they will be applied to the container element.

Name	Description	Default
animationMode	Determines the animation mode when animating data-parallax-...="x;y" attributes center-to-edge: the value will be x at the center and change towards y relative to the distance from the center on all sides. | initial value = x edge-to-edge-x: the value will be x at the left edge and y at the right edge. | initial value = x + (x - y / 2) edge-to-edge-y: the value will be x at the top edge and y at the bottom edge. | initial value = x + (x - y / 2) edge-to-edge-both: the value will be x at the top left corner and y at the bottom right corner. | initial value = x + (x - y / 2) "center-to-edge" | "edge-to-edge-x" | "edge-to-edge-y" | "edge-to-edge-both"	"center-to-edge"
animationReverse	Reverses the animation direction for the specified attribute 'none' : doesn't modify the direction 'all' : reverses direction for all attributes 'all-except-offset' : reverses direction for all attributes except data-parallax-offset 'offset' : reverses direction for the data-parallax-offset attribute 'opacity' : reverses direction for the data-parallax-opacity attribute 'scale' : reverses direction for the data-parallax-scale attribute 'rotation' : reverses direction for the data-parallax-rotation attribute 'skew' : reverses direction for the data-parallax-skew attribute "all" | "all-except-offset" | "offset" | "opacity" | "scale" | "rotation" | "skew" | "none"	"none"
offsetMultiplier	Multiplier applied to all offset values number	1
opacityMultiplier	Multiplier applied to all opacity values number	1
scaleMultiplier	Multiplier applied to all scale values number	1
rotationMultiplier	Multiplier applied to all rotation values number	1
skewMultiplier	Multiplier applied to all skew values number	1
overflowHiddenEnable	Enables/Disables overflow: hidden on the tilt element Note: Disable if you want to set up your own composition with some elements being outside the frame. boolean	true

Default Values

This component modifies the default values of some of react-next-tilt props to better match the provided effect. The list of the modified props and their default values are as follows:

Name	Default
perspective	"1200px"
scale	1.05
shadowEnable	true
shadow	"0 0 1.5rem rgba(0, 0, 0, 0.5)"
CSSTransition	"all 0.3s ease-out"
spotGlarePosition	"all"
spotGlareSizePercent	100

Events/Callbacks

This component has the same events/callbacks as react-next-tilt.

Ref

This component's ref object contains the same properties and works the same way as react-next-tilt's ref.

Credits

Images used in demos are by Yuliya Pauliukevich on vecteezy.com

Inspired by atropos.js

Author

Rashid Shamloo (github.com/rashidshamloo)

License

MIT