npm install react-spring

Why 🤔

React-spring is a cooked down fork of Facebooks animated. It is trying to bridge it with Chenglou's React-motion because both have their pros and cons but could definitively benefit from one another:

React-motion

• Declarative api that doesn't involve manual management of animations
• Covers most of the essentials (springs, lists, transitions, reveals, staggered animations)
• Performance can suffer because components are re-rendered every frame with fresh props
• Can't interpolate between raw state as it doesn't know colors, paths, gradients, etc.

Animated

• Interpolates most web privimites, units and patterns
• Efficiently writes to the dom directly instead of re-rendering components frame by frame
• Managing and orchestrating handles (starting/stopping/waiting/cleaning) can become a real chore
• Missing essential prototypes like mount/unmount transitions

As you see, they're polar opposites. React-spring inherits React-motions api, but simplified, while adding more primitives and being able to interpolate. It also has support for native rendering, where components animate directly in the dom.

Overview 🔭

import { Spring, Transition, Trail, Parallax } from 'react-spring'

Springs (Demo)

A Spring will move data from one state to another. It remembers the current state, value changes are always fluid.

<Spring from={{ opacity: 0 }} to={{ opacity: 1 }}>
    {styles => <div style={styles}>i will fade in</div>}
</Spring>

Mount/unmount Transitions (Demo)

Transition watches elements as they mount and unmount, it helps you to animate these changes.

<Transition
    keys={items.map(item => item.key)}
    from={{ opacity: 0, height: 0 }}
    enter={{ opacity: 1, height: 20 }}
    leave={{ opacity: 0, height: 0 }}>
    {items.map(item => styles => <li style={styles}>{item.text}</li>)}
</Transition>

2-state Reveals (Demo)

Given a single child instead of a list you can reveal components with it.

<Transition
    keys={toggle ? 'A' : 'B'} 
    from={{ opacity: 0 }} 
    enter={{ opacity: 1 }} 
    leave={{ opacity: 0 }}>
    {toggle ? ComponentA : ComponentB}
</Transition>

Trails and staggered animations (Demo)

Trail animates the first child of a list of elements, the rest follow the spring of their previous sibling.

<Trail from={{ opacity: 0 }} to={{ opacity: 1 }} keys={items.map(item => item.key)}>
    {items.map(item => styles => <div style={styles}>{item.text}</div>)}
</Trail>

Parallax and page transitions (Demo)

Parallax allows you to declaratively create page/scroll-based animations.

<Parallax pages={2}>
    <Parallax.Layer offset={0} speed={0.2}>first Page</Parallax.Layer>
    <Parallax.Layer offset={1} speed={0.5}>second Page</Parallax.Layer>
</Parallax>

Additional demos: Vertical scroll | Animated graphs | Animated todoMVC | Drag n drop

API overview 📖

For a raw documentation of all possible properties look here.

Springs and interpolation

You can interpolate almost everything, from numbers, colors, svg-paths, percentages, arrays to string patterns:

<spring to={{
    start: toggle ? '#abc' : 'rgb(10,20,30)',
    end: toggle ? 'seagreen' : 'rgba(0,0,0,0.5)',
    stop: toggle ? '0%' : '50%',
    scale: toggle ? 1 : 2,
    rotate: toggle ? '0deg' : '45deg',
    path: toggle ? 'M20,380 L380,380 L380,380 Z' : 'M20,20 L20,380 L380,380 Z' }}>

Render props

Don't like the way render props wrap your code?

const Header = ({ children, ...styles }) => (
    <h1 style={styles}>
        {children}
    </h1>
)

const App = ({ color, children }) => (
    <Spring to={{ color }} render={Header}>
        {children}
    </Spring>
)

Et voilà! Header animates on prop changes! Props that Spring doesn't recognize will be spread over the receiving component, including children if you use render to refer to the render-child.

Native rendering (Demo)

By default we'll render the receiving component every frame as it gives you more freedom to animate. In situations where that becomes expensive add the native flag and animations will now be applied directly to the dom. The flag is available for all primitives (Spring, Transition & Trail, Parallax is native by design).

Just be aware of the following conditions:

1. It only animates standard styles and element props, the values you receive are opaque objects, not regular values
2. Receiving elements must be animated.[elementName], for instance div becomes animated.div
3. If you need to interpolate styles use the template string literal

import { Spring, animated, template } from 'react-spring'

<Spring native to={{ path, rotate, scale }}>
    {({ rotate, scale, path }) => (
        <animated.svg style={{ transform: template`rotate(${rotate}) scale(${scale})` }}>
            <g><animated.path d={path} /></g>
        </animated.svg>
    )}
</Spring>

Transitions

Animates children as they mount and unmount. from denotes base styles, enter styles are applied when objects appear, leave styles are applied when objects disappear. Keys and children have to match in their order! The keys are the same that you would provide in any other looping situation.

import { Transition } from 'react-spring'

<ul>
    <Transition
        keys={items.map(item => item.key)}
        from={{ opacity: 0, height: 0 }}
        enter={{ opacity: 1, height: 20 }}
        leave={{ opacity: 0, height: 0 }}>
        {items.map(item => styles => <li style={styles}>{item.text}</li>)}
    </Transition>
</ul>

You can use this prototype for two-state reveals, simply render a single child that you can switch out for another.

<Transition
    keys={toggle ? 'ComponentA' : 'ComponentB'} 
    from={{ opacity: 0 }} 
    enter={{ opacity: 1 }} 
    leave={{ opacity: 0 }}>
    {toggle ? ComponentA : ComponentB}
</Transition>

Trails/Staggered transitions

Trail animates the first child of the list you pass, the others will follow in a trailing motion. The api is similar to Transition though it will assume your list is fixed.

import { Trail } from 'react-spring'

<Trail from={{ opacity: 0 }} to={{ opacity: 1 }} keys={items.map(item => item.key)}>
    {items.map(item => styles => <div style={styles}>{item.text}</div>)}
</Trail>

Parallax and page transitions

Parallax creates a scroll container. Throw in any amount of layers and it will take care of moving them in accordance to their offsets and speeds.

Parallax.pages determines the total space of the inner content where each page takes 100% of the visible container. Layer.offset determines where the layer will be at when scrolled to (0=start, 1=1st page, ...). Layer.speed shifts the layer in accordance to its offset, values can be positive or negative.

import { Parallax } from 'react-spring'

<Parallax pages={3} scrolling={false} horizontal ref={ref => this.parallax = ref}>
    <Parallax.Layer offset={0} speed={0.5}>
        <span onClick={() => this.parallax.scrollTo(1)}>
            Layers can contain anything
        </span>
    </Parallax.Layer>
</Parallax>

---

API | Changelog