Chain-drive NPM

ChainDrive

ChainDrive is a React.js component library dedicated to creating complex transitions without adding noise in your code. React Transition Group's Transition component is the core workhorse of this library, so it's a basic understanding of it is necessary there use.

Inspired by Anime.js + React Transition Group by Uday Hiwarale

Features

AnimeJs HOC
Timeout calculation

Getting Started

To install the library in you project run npm install animejs react-transition-group chain-drive or yarn add animejs react-transition-group chain-drive.

Usage

Using the library is quite simple.

import React from 'react;
import { render } from 'react-dom';
import { Chain, withAnimeJs } from 'chain-drive';

const Container = withAnimeJs( 
    React.forwardRef( ( { animeRef, context, ...r }, ref ) => (
        <div ref={ ref } { ...r }></div>
    )
) );

const App = () => (
    <Chain id="app" in={ true }>
        <Container
            id="section"
            entering={ {
                opacity: 1,
                translateX: [ '-100%', 0 ],
                duration: 600,
            } }
            exiting={ {
                opacity: 0,
                translateX: [ 0, '+100%' ],
                duration: 450,
            } }
            exited={ { opacity: 0 } }
        >
    </Chain>
)

render( <App />, document.getByElementId( 'app' ) );

Transition Components

Chain

Props

id string|number required - ChainContext unique identifier
order string - Chain transition order used for Chain and immediate child InnerChain component. Valid options are fifo first-in first-out, filo first-in last-out, lifo last-in first-out, and lilo last-in last-out. Defaults to fifo.

Notes

Functions as a relay for the transition and a wrapper to React Transition Group's Transition component. It stores the state of Transition component and passes it to the ChainContext context using React.js' Context API for use by all child components. All props for the Transition component are passed through and work like normal, except timeout. The timeout prop defaults to the highest enter and exit timeouts of all mounted direct child withAnimeJs( component )s.

<Chain id="app" in={ true }>
    ...
</Chain>

InnerChain

Props

id string|number required - ChainContext unique identifier
in boolean - extra conditional used to determine in prop Chain component

Notes

Functions as a middleman of sorts by retrieving the state of the closest parent Chain or InnerChain component through context and passing it down to its children.

<Chain id="app" in={ true }>
    <InnerChain>
        ...
    </InnerChain>
</Chain>

Animation HOCs

withAnimeJs

Props

id string|number required - ChainContext unique identifier
state string - component's current state
processTimeout function - callback used to calculate parent Chain/InnerChain timeout

Notes

A HOC that wraps and executes a series of Anime.js calls on its children. Anime.js manipulates DOM and doesn't interact with the VirtualDOM React uses, meaning for it to properly target elements the ref prop must be set somewhere on the wrapped component, like example below.

const Container = withAnimeJs( 
    React.forwardRef( ( { animeRef, context, children, ...r }, ref ) => (
        <div ref={ ref } { ...r }>
            <span>Wrapped</span>
            { children }
        </div>
    )
) );

The resulting component can be animated by state. This is done by providing anime.js parameters as a prop named after the corresponding state. You can see an example of this in the following example. Consult Anime.js' documentation for more info. processTimeout is a callback used to calculate the timeout prop used for a parenting Chain or InnerChain component. The default callback is pretty robust and isn't used during stand-alone use so you'll rarely ever have to set this.

    <Container
        id="section"
        state="hello"
        hello={ {
            opacity: 1,
            translateX: [ '-100%', 0 ],
            duration: 600,
        } }
        goodbye={ {
            opacity: 0,
            translateX: [ 0, '+100%' ],
            duration: 450,
        } }
    >
        ...
    </Container>

When no state prop is provided, it's set to that of the nearest parent ChainContext. If none is found, it uses the default which is unmounted. Using in conjournment with the Chain and InnerChain components can allow for centralized state-management and complex transitions without much effort.

Examples

Flashy Text

A recreation of couple of Tobias Ahlin's Moving Letters examples. Styled Components are used for the base styling, but this can easily be replace with plain css.