React Animation 👌

This package provides components you can use to easily add animation to your components, along with a set of pre-built animations and timing functions.

Demos

You can see each of the components and animations that are included on this demo page.

Usage

npm install -s @nearform/react-animation

Components

The following components can be used to easily add animation to specific circumstances.

AnimateOnChange

It can be helpful to let users know when something has changed in our UI. This component aims to help by adding an animation to any content that changes.

<AnimateOnChange>{value or child components}</AnimateOnChange>

The AnimateOnChange component will automatically fade out old content and fade in the new content when the content changes. This could be a number or string or any child components.

The following (optional) properties can be used:

• animationIn
• animationOut
• className
• durationOut
• style

By default, the animation used is a fade out and in. You can specify an animation for both the out (when the old content is removed) and in (when new content is shown) stages of the animation.

You can reference these by name, for example:

<AnimateOnChange animationIn="popIn" animationOut="popOut">...</AnimateOnChange>

This will apply a popOut animation when removing the old content, and a popIn animation on the new content.

Custom animationInand animationOut values

You can specify a built-in animation by name and it will call in the relevant animation property for you. If you prefer you can also supply a string here such as my-animation 500ms ease-out forwards. This way you can specify your own animation, as long as you've defined the my-animation keyframes somewhere.

ClassName

If you need more control, such as animating child components of pseudo-elements, you can supply a class name. By default, the component will add a animate-on-change class along with either animate-on-change-in and animate-on-change-out depending on the stage of the animation.

You can supply a className of "foo" and it will apply foo, foo-in and foo-out as necessary.

HideUntilLoaded

Nobody likes a half-downloaded image appearing when rendering our UI. This component helps by hiding any children content until a specified image has finished downloading.

<HideUntilLoaded imageToLoad="[IMAGE_URL]">Your content</HideUntilLoaded>

By default the component will apply an opacity of 0 and then a transition when loading has completed. This will fade in the fully downloaded content.

You can supply animationIn an animation name to use that instead of the default fade.

Spinners

You can specify any React component as a "spinner" or loading indicator. This will be shown while the loading is taking place, and then removed once the content is ready to be shown.

import MySpinner from '../MySpinner' // This could be an animated SVG or any React component

<HideUntilLoaded imageToLoad="[IMAGE_URL]" Spinner={Spinner}>Your content</HideUntilLoaded>

Animations

This package includes some pre-built animations along with their associated keyframes. As well as supplying the animation names to the above components, you can also apply these animations directly to your components:

import { animations } from '@nearform/react-animation'

const style = {
  animation: animations.popIn
}

<MyComponent style={style} />

In this example, popIn evaluates to pop-in 500ms cubic-bezier(0.19, 1, 0.22, 1) forwards.

The following animations are included:

• fadeIn
• fadeOut
• fadeInUp
• popIn
• popOut
• bounceIn
• bounceOut
• slideIn
• slideOut

Using your own styles

You can pass any custom styles into the AnimateOnChange and HideUntilLoaded using the style property.

Easings

As well as pre-built animations, this package includes a range of timing functions you can use in animations and transitions.

The full set can be seen in action on the demo page.

You can apply these to your component styles like so:

import { easings } from '@nearform/react-animation'

const style = {
  animation: `pop-in ${easings.easeOutExpo} 500ms forwards`
}

<MyComponent style={style} />

The full list includes:

• linear
• easeInSine
• easeOutSine
• easeInOutSine
• easeInQuad
• easeOutQuad
• easeInOutQuad
• easeInCubic
• easeOutCubic
• easeInOutCubic
• easeInQuart
• easeOutQuart
• easeInOutQuart
• easeInQuint
• easeOutQuint
• easeInOutQuint
• easeInExpo
• easeOutExpo
• easeInOutExpo
• easeInBack
• easeOutBack
• easeInOutBack

FAQ

What is this for?

This package is for situations where UI needs to move or animate. These situations could include when data changes, or when an item takes a while to fully load a large background image.

The package also contains pre-built animations that can be applied to components.

Why not use ReactTransitionGroup for many of the use cases?

ReactTransitionGroup is a useful and powerful approach to adding animation to elements, and you could certainly do most of what this package does with it. However you would need to define animation keyframes manually, and style each stage of each animation using classes.

This package aims to help when adding UI movement by making common actions easier. So for situations such as when data changes, or when an element needs to wait until loading has completed before animating into place, this package offers an easier way.

One benefit of this is ensuring that the animations you add to UI elements "feel" the same across a site or app.

ReactTransitionGroup provides a good approach to timing and managing classes but doesn't bring any animations or timing functions.

License

Copyright 2018 nearForm

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.

You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS,

WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

See the License for the specific language governing permissions and limitations under the License.