react-gsap-enhancer

, Demos, Why?, How it works?, Usage, API, ---------------, ------------, ------------------------------, ---------------, -----------, A React component enhancer for applying GSAP animations on components without side effects.

For simple use cases you might not need this tool. See this egghead.io tutorial.

Developed as part of the Animachine project.

Requirements:

• From v0.2 react-gsap-enhancer requires react v0.14+. Check out this release notes for upgrading from v0.1.x.
• GSAP v1.18+ (NPM, CDN)

Demos

• Playground
• update the component while it's animating
• control timeline with component events
• use options (ES5)
• use with react-addons-transition-group (ES5)
• and more...!
• CodePen
• Material Login Dialog

Why?

We have great tools (like react-motion, or Animated) to animate the state and props of our React components but if you ever needed to create a longer animation sequence with React you can still feel the desire to reach out for a tool like GSAP which makes it easy to compose your animation and apply it on the DOM with its super performance and bulit in polyfills. Unfortunately, if you let anything to mutate the DOM of a component, React can break on the next update because is suppose that the DOM looks exacly the same like after the last update. This tool is a work around for this problem.

How it works?

It's pretty simple: in every render cycle:

• after each render save the attributes of the rendered DOM elements than start/restart the added animations.
• before each render stop the animations and restore the saved attributes (so React will find the DOM as it was after the update)

In this way you can even update a style of an element (like transform: 'translateX(${mouse.x})') while you animating the same style relative to its original value (like: .to(node, 1, {x: '+=300', yoyo: true})

Check it out!

Usage

First you have to enhance the component with react-gsap-enhancer:

ES5

var GSAP = require('react-gsap-enhancer')
var MyComponent = GSAP()(React.createClass({
  render: function() {/*...*/}
}))

ES6

import GSAP from 'react-gsap-enhancer'

class MyComponent extends Component {
  render() {/*...*/}
}

export default GSAP()(MyComponent)

ES7

import GSAP from 'react-gsap-enhancer'

@GSAP()
export default class MyComponent extends Component {
  render() {/*...*/}
}

Now you can attach animations to the component with addAnimation(animationSource). The animationsSource is a function that returns a GSAP Animation (ex. TweenLite, or TimelineMax) like this:

function moveAnimation(utils) {
  return TweenMax.to(utils.target, 1, {x: '+=123'})
}

the utils.target refers to the root node of the component but you can select any of it's children by they props in the good old jQuery style:

function moveAnimation({target}) {//just ES6 syntax sugar
  var footer = target.find({type: 'footer'})
  var buttons = footer.findAll({type: 'button'})
  ...
}

and later in a component you can use it like:

...
handleClick() {
  var controller = this.addAnimation(moveAnimation)
...

the addAnimation() returns a controller object that has the same API like the original GSAP Animation so you are free to control it like:

...
handleStartLoad() {
  this.progressAnim = this.addAnimation(progressAnim)
  this.otherAnim.timeScale(3.4).reverse()
}
handleProgress(progress) {
  this.progressAnim.tweenTo(progress)
}
...

API

addAnimation()

• enhancedComponent.addAnimation(animationSource[, options]) -> controller: Add an animation to the component with the given source and returns a Controller for it. The options will be passed to the animationSource.

controller

Wraps the GSAP Animation returned from the animationSource. It's exposing the following GSAP API methods:
For TweenMax and TweenLite:

delay*,
duration*,
eventCallback,
invalidate,
isActive,
pause,
paused,
play,
progress,
restart,
resume,
reverse,
reversed,
seek,
startTime*,
time,
timeScale,
totalDuration*,
totalProgress*,
totalTime*,

For TimelineMax and TimelineLite:

currentLabel,
duration*,
endTime*,
eventCallback,
from,
fromTo,
getLabelAfter,
getLabelBefore,
getLabelArray,
getLabelTime,
invalidate,
isActive,
pause,
paused,
play,
progress,
restart,
resume,
reverse,
reversed,
seek,
startTime*,
time,
timeScale,
totalDuration*,
totalProgress*,
totalTime*,
tweenFromTo,
tweenTo,

Notes:

• Some of the methods above doesn't available for TweenLite and TimelineLite. Please check the GSAP docs for more detailes.
• controller.kill() will also remove all the effects the animation made on your component.
• As you can see the editor methods (like .to() or .add()) aren't exposed by the controller so you can only use them inside the animationSource function while you construct the animation.

* Trough the controller you can only get values with these methods.

var controller = this.addAnimation(animationSource)
controller.timeScale(2).play()

animationSource

• ({target, options}) -> GSAP Animation

A function that returns a GSAP Animation.

function animationSource(utils) {
  return TweenMax.to(utils.target, 1, {x: 100})
}
this.addAnimation(animationSource)

target

jQuery like object that refers to the root component and lets select its children with chainable find methods and selectors.

• target.find(selector): returns with the first match
• target.findAll(selector): returns with all the matches
• target.findInChildren(selector): returns with the first match in the direct children
• target.findAllInChildren(selector): returns with all the matches in the direct children

function animationSource(utils) {
  var button = utils.target.findAll({type: 'button'}).find({role: 'submit'})
  return TweenMax.to(button, 1, {x: 100})
}

options

Arbitrary object. Passed to the addAnimation call as the second argument and and will be passed to the animationSource

this.addAnimation(animationSource, {offset: this.props.offset})

...

function animationSource(utils) {
  return TweenMax.to(utils.target, 1, {x: utils.options.offset})
}

selector

Selectors are usually simple objects and the "find" functions are using it to select the elements with matching props. Ie. {key: 'head'}, {color: 'red'}, and {key: 'head', color: 'red} are all matches to <div key='head' color='red'/>.

I'm looking forward for your feedback!