component-animators v0.1.6

component-animators

Please Note: The component-animators library is provided for educational purposes only. May not be suitable for production use.

Overview

component-animators is a React Component library which offers a React higher-order component allowing for D3 transitions (d3-transition) to be added to React components in a reusable manner.

To make multiple D3 transitions easier to compose, the component-animators library allows for animations to be encoded as either:

• a single animation. Created from a single D3-transition.

• an in-order animation. Created from a collection of animations. Can embed further in-order, together or single animations to any depth. All animations encoded in the collection start one after the other (sequentially), with the next transition in the collection only starting after the first completes.

• a together animation. Can embed in-order, together or single animations. All animations encoded in the collection start at the same time (simultaneously). Completes once all animations in the collection have completed.

• a complex animation. Created by nesting in-order and together animations.

Prerequisites

To be able to use the component-animators library, the library assumes that the library consumer has an understanding of the d3-transition library and how d3-transitions work, as well as a basic understanding of React.

See also: The d3-transition Documentation .

API

The library exports four functions:

• single(transitionDescription)

• inOrder(collection)

• together(collection)

• componentAnimator(animationTrigger,animation)(TargetComponent)

The API Reference documentation provides a detailed reference for the library's functions and is designed to be used as a quick point of reference for users already familiar with the library ^api-documentation-appendix.

^api-documentation-appendix: The API document is also replicated as an appendix for ease of reference.

Quick Start

Installation

component-animators is available in its packaged form as an npm package.

The command to install the component-animators package is:

npm install -P component-animators

Import

Once the package has been installed, the library's functions can be imported into a JavaScript module using the following syntax:

import {
    single, inOrder, together, componentAnimator 
} from component-animators;

Creating an Animatable Component

To prepare the React component for use by the component-animators library, the React component needs to be transformed into an animatable component. Within the context of the component-animators library, an animatable component is a React component with a ref forwarded from the component to a valid HTML tag inside of the component. This relies on the React.forwardRef method.

import React from 'react';
...

const AnimatableComponent = React.forwardRef((props, ref) => 
    <div ref={ref} />
);

The approach recommended by this library is to add the ref to the outermost HTML element rendered.

See also: The React Documentation on Forwarding Refs.

Creating an Animation

A single animation is created by passing to the library's single function, which is a factory function for creating single animation objects. For example:

import { single } from 'component-animators';

const singleAnimation = single((transition, props) => 
    transition.duration(200).style('color', 'red');
);

The transition passed into the transitionDescription function is provided with a selection targeting the DOM tag specified as the ref target for the animatable component and should be returned from the function.

The in-order and together animation factory functions take a collection of animations. As an example of the creation of an in-order animation:

import { inOrder, single } from 'component-animators';

const inOrderAnimation = inOrder([
    single(transitionDescription),
    single(transitionDescription),
]);

Adding the Animation to the Animatable Component

The component-animator function is called in two parts: the first call takes two arguments (a trigger and an animation), whereas the second call takes the name of the React component that the animation is being added to.

import { componentAnimator } from 'component-animators';
... 

const AnimatedComponent = componentAnimator(
    trigger, 
    animation,
)(TargetComponent);

The trigger that needs to be provided to the componentAnimator function has the following signature: props => boolean;

The props are the same props that will be received by the TargerComponent and can be used to check that a condition is met. To make the same animation play every time that the component updates, pass the following trigger: () => true;

To work with JSX, the name for the augmented component should use an initial upper case letter.

Complete Example

Bringing this all together, the below example demonstrates a simple React component which whenever the component updates will transition to show the new message.

import React from 'react';
import { single, componentAnimator } from 'component-animators';

const animation = 
    single((t, props) => t.duration(200).text(props.message);
    
const alwaysTrigger = 
    () => true;

const AnimatableComponent = React.forwardRef(props, ref => 
    <div ref={ref}>props.message</div>);

const AnimatedComponent = componentAnimator(alwaysTrigger, animation)(AnimatableComponent);