react-parallax-pro

React Parallax Pro Components

This package adds support to create Parallax Components in React. Although there might be a few similar packages on the market, not all of them are the right suit for every project.

Version ^1.5.0

This version allows you to change between "global" and "local" element object to choose whether you prefer to perform animation based on local offset of an element (for example a child container) or global offset that is derived by recursive addition of each parent's offset until reaching body element.

Version ^1.4.0

This version brings new experimental API including useParallax hook and <UseParallax> component. While this project is still in development, Parallax component from previous version works as in specification below in order to prevent conflicts.

Starting this version we recommend to use <UseParallax> component which is utilizing the new useParallax() hook. You can import it to your project and use in sample like so:

import { UseParallax } from 'react-parallax-pro'
// ...

const App = () => {
    // ...

    const pxConfig = {
        // Possible values: "bottom" | "center" | "top" | number
        startScroll: "center",
        fadeIn: { /* ... */ },
        fadeOut: { /* ... */ },
        // NOTE: do not use `fadeIn` or `fadeOut` while using `keyframes`!
        keyframes: { /* ... */ },
    }

    return (
        <UseParallax {...pxConfig} >
            {({isTransitioning, inView}) => (
                <YourComponent>
                    // ... The rest of components

                    // You can pass exposed variables into components as well, ex:
                </YourComponent>
            )}
        </UseParallax>
    )
}

New API includes ability to control fadeIn and fadeOut animation to allow more customization. It also includes keyframes which is currently experimental and it allows to manually control the animation/transition step-by-step. Do not use fadeIn/fadeOut if you're using keyframes - it won't work.

What makes this library unique?

You can create more advanced scroll-based animations without breaking your existing styled elements/components. Simply wrap your components within <Parallax> and customize them to your likings.

Features

Some of the key Features include:

• scroll detection transitions
• animate elements based on user's scroll
• window + scroll detection
• color transitions
• background transitions
• gradient transitions
• translate, rotate, scale transformations
• offset and delay animations
• filter animations
• fade in transitions
• fade out transitions
• *keyframed animations

Get Started

Add package to your dev dependencies

npm i --save-dev react-parallax-pro

API

How to import

Import package into your existing react component like so:

import { UseParallax } from 'react-parallax-pro';

How to use

Then you'll want to wrap your component between <Parallax> MyComponent </Parallax> JSX

const App = (props) => {

    const pxConfig = {
        ...
    }

    return (
        <Parallax {...pxConfig} {...props}>
            <YourComponent />
        </Parallax>
    )
}

Components

This library is simple yet powerful. There is useParallax hook as well as wrapped <UseParallax> components for you to start with out of the box!

useParallax hook

It allows you to control any component and turn it into a Parallax Component. This library already provides <UseParallax> component that implements this hook, though you can use it on your own components as well.

<UseParallax> Component

This is a component that can wrap other components to provide Parallax control. At the moment the usage is following:
Import:

import { UseParallax } from "react-parallax-pro";

Then use like so:

<UseParallax {...pxConfig}>
    <YourComponent />
</UseParallax>

You can also use Function as children technique to get returned value status that can be destructured to access following properties:

• isTransitioning: boolean;
• inView: boolean; All these values are optional, you can choose any and pass to other components.

Example:

<UseParallax {...pxConfig}>
    {({isTransitioning, inView}) => (
        <YourComponent status={isTransitioning} inView={inView}>
            // ...
        </YourComponent>
    )}
</UseParallax>

Parallax Component's Config API

Inside the pxConfig you can pass following arguments:

interface UseParallaxAPI {
    /* Specifies when to detect element based on scroll and window position */
    startScroll? = 'top' | 'center' | 'bottom' | number; // --> 'bottom'
    
    /* Specifies how long (in px) the transition will take. */
    endScroll?: number | '${number}%'; // --> '100%' of container's height

    /* Offset animation by `number` of pixels before it starts transitioning. */
    offset?: number; // --> 0

    /* If set to `true`, transition will NOT be performed. */
    disabled?: boolean; // --> false

    /* If set to `true`, scroll transition will extend its length to fit all animations. */
    extend?: boolean;

    /* Creates Fade In smooth transition starting at `startScroll` position. */
    fadeIn?: IParallaxAnimationProps;

    /* Creates Fade Out smooth transition starting at `endScroll` position. */
    fadeOut?: IParallaxAnimationProps;

    /* Compose custom animation based on an array of keyframes. */
    // NOTE: Do NOT use `fadeIn` or `fadeOut` with keyframes.
    keyframes?: IParallaxKeyframe[];

    /* Allows to pass custom styles via styled-components or other css modules */
    className?: string;

    // Pass `JSX Component` or a `Function as Children` 
    children?: ((status: ParallaxStatus) => JSX.Element) | JSX.Element | React.ReactNode;
}

Parallax Supported Effects

Most of the transitions are made to have the easiest syntax. Effects take an array with start and end properties to transition between for a specified amount of time (length of the component or custom length/offset values).

fadeIn AND fadeOut take following arguments:

interface IParallaxAnimation {
    /* Transitions transparency (0 - 1 ) */
    opacity?: [start: number, end: number];

    /* Transitions background color */
    background?: [start: Color, end: Color];

    /* Animates component's transformations */
    transform?: TransformProps;

    /* Smoothly animates gradient colors */
    gradient?: GradientProps;

    /* Transition filters */
    filter?: FilterProps;
}

Properties' interface description

Let's explain properties Color, TransformProps, GradientProps and FilterProps.

Color Property

Property Color MUST be either RGBA array:

type RGBA = [r: number, g: number, b: number, a: number]

OR hexadecimal number #000 | #ffff | #rrggbb | #rrggbbaa

Transform Property

Transformation is exactly like you would use it in CSS, but passed as an Array of values instead. So you'll pass the array of start -> end values.

interface TransformProps {
    /* Translate component's position (X, Y) */
    translate?: [
        X: [start: number, end: number],
        Y: [start: number, end: number]
    ];

    // NOTE: If `translate` is set, `translateX` and `translateY` will be ignored. */
    /* Translate component's horizontal position */
    translateX?: [start: number, end: number];

    /* Translate component's horizontal position */
    translateY?: [start: number, end: number];

    /* Rescale component (1.0 is default) */
    scale?: [start: number, end: number];

    /* Rotate component by `number` degrees */
    rotate?: [start: number, end: number];
}

Filter Property

Filters follow exactly the same syntax as Transform and properties are self-explanatory I suppose.

export interface FilterProps {
    blur?: [start: number, end: number];
    brightness?: [start: nmber, end: number];
    contrast?: [start: numbuer, end: number];
    grayscale?: [start: number, end: number];
    hueRotate?: [start: number, end: number];
    opacity?: [start: number, end: number];
    saturate?: [start: number, end: number];
    sepia?: [start: number, end: number];
}

Gradient Property

Now for the gradients to work we'll need tot take slighlty different approach.

• Values start and end are required.
• You MUST pass at least 2 values into the Color[] array
• You MUST pass the same number of elements to both start and end
• Value type is optional and defaults to "linear"
• Value dir is optional and defaults to [0, 0]

export interface GradientProps {
    /* Choose whether to use `linear` or `radial` gradient */
    type?: "linear" | "radial" | undefined;

    /* Animate (rotate) the gradient's curve */
    dir?: [start: number, end: number] | undefined;

    /* Array of colors to start with */
    start: Color[];

    /* Array of colors to finish animtation on */
    end: Color[];
}

Keyframes

Keyframes have slightly different API. Each keyframe require parameters: length and animations.
There is optional extend: boolean that if set to true will automatically expand container's animation length in order to fit the full transition:

Example usage:

import { UseParallax } from 'react-parallax-pro';
const App = (props) => {
    
    const pxConfig = {
        startScroll: "bottom",
        keyframes: [
            { length: 300, background: "#000" },
            { length: 200, background: "#eca" },
            { length: 300, background: "#3cf" },
            { length: 500, background: "#fff" },
            { length: 200, background: "#000" },
        ]
    }

    return (
        <UseParallax {...pxConfig} {...props}>
        // ...
        </UseParallax>
    )
}
    

Interface

It's important Keyframes instead of array take single values, pretty much same as CSS properties. Hence instead of passing arrays, you can pass any supported property as is and the interpolations will be automatically calculated for you. NOTE: You MUST pass at least 2 keyframes for animation to work properly.

export interface IParallaxKeyframe extends IParallaxKeyframeAttributes {
    /* REQUIRED - Length of animation in `px` */ 
    length: HTMLValueType;

    /* If true, animation will hold previous keyframe's state */
    hold?: boolean;

    /* Transform */
    translate?: [X: number, Y: number];
    translateX?: number;
    translateY?: number;
    scale?: number;
    rotate?: number;

    /* Opacity */
    opacity?: number;

    /* Background */
    background?: Color;

    /* Gradient */
    gradient?: {
        colors: Color[],
        type?: 'linear' | 'radial' | undefined,
        dir?: number
    }

    // Filters //
    blur?: number;
    brightness?: number;
    contrast?: number;
    grayscale?: number;
    hueRotate?: number;
    saturate?: number;
    sepia?: number;

Last Words

Alright, that's all for now. This library is still in development and if you can, please let me know your thoughts on it!

What would you use it for?

FAQ

How to fix overflowing components?

When animating transformation, such as transform, scale or rotate with <UseParallax> component you might notice overflows out of the container. This may cause various glitches. In order to fix it, simply wrap all your Parallax elements within a wrapper with overflow: hidden style. Example:

<div style={{overflow: hidden}}>
    <UseParallax><YourComponent1 /><UseParallax />
    <UseParallax><YourComponent2 /><UseParallax />
    <UseParallax><YourComponent3 /><UseParallax />
</div>

How to add share animation between components?

In future versions you'll be able to use provider to set default values (that's in work currently). As of now you can create a pxConfig variable and apply it to multiple components.

// Your animation
const pxConfig={ ... }

const app = () => {
    //...
 
    return (
        <div style={{overflow: hidden}}>
            <UseParallax {...pxConfig}><YourComponent1 /><UseParallax />
            <UseParallax {...pxConfig}><YourComponent2 /><UseParallax />
            <UseParallax {...pxConfig}><YourComponent3 /><UseParallax />
        </div>
    )
}

Support

Plese visit github repository here: https://github.com/dyanechi/react-parallax-pro if you'd like to contribute or have any questions, issues or anything else :)

TODO

• Update API ✓
• Improve control over animations
• Add easing functions
• Fix small bugs
• Optimize performance