npm package: @nearform/react-animation
Description: Helpful animation components for adding movement to your React components
Author: NearForm
Latest version: 1.0.6
Deprecated: This package has been renamed react-animation

# React Animation 👌

[![Build Status](https://travis-ci.org/nearform/react-animation.svg?branch=master)](https://travis-ci.org/nearform/react-animation)
[![NPM version](https://img.shields.io/npm/v/@nearform/react-animation.svg)](https://www.npmjs.com/package/@nearform/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](https://nearform.github.com/react-animation/).

## 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 `animationIn`and `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](https://nearform.github.io/react-animation/).

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.