# react-gsap-enhancer

**Repository Path**: mirrors_azazdeaz/react-gsap-enhancer

## Basic Information

- **Project Name**: react-gsap-enhancer
- **Description**: Use the full power of React and GSAP together
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2022-01-07
- **Last Updated**: 2026-09-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# react-gsap-enhancer [![Build Status](https://img.shields.io/travis/azazdeaz/react-gsap-enhancer.svg?style=flat-square)](https://travis-ci.org/azazdeaz/react-gsap-enhancer) [![Coveralls branch](https://img.shields.io/coveralls/azazdeaz/react-gsap-enhancer/master.svg?style=flat-square)](https://coveralls.io/github/azazdeaz/react-gsap-enhancer)  [![npm](https://img.shields.io/npm/dm/react-gsap-enhancer.svg?style=flat-square)](https://www.npmjs.com/package/react-gsap-enhancer) ![maintainance](https://img.shields.io/badge/actively%20maintained-%20not%20%3A\(%20sorry-red.svg?style=flat-square)


[![Join the chat at https://gitter.im/azazdeaz/react-gsap-enhancer](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/azazdeaz/react-gsap-enhancer?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

|[Demos](#demos)|[Why?](#why)|[How it works?](#how-it-works)|[Usage](#usage)|[API](#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](https://egghead.io/lessons/react-using-tweenmax-with-react).

*Developed as part of the [Animachine project](https://github.com/animachine/animachine).*

**Requirements:** 
 - From v0.2 react-gsap-enhancer requires **[react v0.14+][react-npm]**. Check out [this release notes](https://github.com/azazdeaz/react-gsap-enhancer/releases/tag/v0.2.0) for upgrading from v0.1.x.
 - **GSAP v1.18+** ([*NPM*][gsap-npm], [*CDN*][gsap-cdn])

### Demos
 - Playground
  - [update the component while it's animating](http://azazdeaz.github.io/react-gsap-enhancer/#/demo/update-and-animate-transform)
  - [control timeline with component events](http://azazdeaz.github.io/react-gsap-enhancer/#/demo/morphing-search-input)
  - [use options (ES5)](http://azazdeaz.github.io/react-gsap-enhancer/#/demo/sending-options-to-the-animation-source)
  - [use with react-addons-transition-group (ES5)](http://azazdeaz.github.io/react-gsap-enhancer/#/demo/using-transition-group)
  - [and more...!](http://azazdeaz.github.io/react-gsap-enhancer/#/demo/select-target-with-options)
 - CodePen
  - [Material Login Dialog](http://codepen.io/azazdeaz/pen/yYavVK?editors=001)

### 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 mutate the DOM of a component, React can break on the next update because it is supposed that the DOM looks exacly the same like after the last update. This tool is a workaround 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 then 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 animating the same style relative to its original value (like: ```.to(node, 1, {x: '+=300', yoyo: true}```)

>[Check it out!](http://azazdeaz.github.io/react-gsap-enhancer/#/demo/update-and-animate-transform) 

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

**ES5**
```javascript
var GSAP = require('react-gsap-enhancer')
var MyComponent = GSAP()(React.createClass({
  render: function() {/*...*/}
}))
```
**ES6**
```javascript
import GSAP from 'react-gsap-enhancer'

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

export default GSAP()(MyComponent)
```
**ES7**
```javascript
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:
```javascript
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 their props in the good old jQuery style:
```javascript
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:
```javascript
...
handleClick() {
  var controller = this.addAnimation(moveAnimation)
...
```
the ```addAnimation()``` returns a [controller object](#controller) that has the same API like the original GSAP Animation so you are free to control it like:
```javascript
...
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```: Adds 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](http://greensock.com/docs/#/HTML5/GSAP/TweenMax/delay/)\*,
[duration](http://greensock.com/docs/#/HTML5/GSAP/TweenMax/duration/)\*,
[eventCallback](http://greensock.com/docs/#/HTML5/GSAP/TweenMax/eventCallback/),
[invalidate](http://greensock.com/docs/#/HTML5/GSAP/TweenMax/invalidate/),
[isActive](http://greensock.com/docs/#/HTML5/GSAP/TweenMax/isActive/),
[pause](http://greensock.com/docs/#/HTML5/GSAP/TweenMax/pause/),
[paused](http://greensock.com/docs/#/HTML5/GSAP/TweenMax/paused/),
[play](http://greensock.com/docs/#/HTML5/GSAP/TweenMax/play/),
[progress](http://greensock.com/docs/#/HTML5/GSAP/TweenMax/progress/),
[restart](http://greensock.com/docs/#/HTML5/GSAP/TweenMax/restart/),
[resume](http://greensock.com/docs/#/HTML5/GSAP/TweenMax/resume/),
[reverse](http://greensock.com/docs/#/HTML5/GSAP/TweenMax/reverse/),
[reversed](http://greensock.com/docs/#/HTML5/GSAP/TweenMax/reversed/),
[seek](http://greensock.com/docs/#/HTML5/GSAP/TweenMax/seek/),
[startTime](http://greensock.com/docs/#/HTML5/GSAP/TweenMax/startTime/)\*,
[time](http://greensock.com/docs/#/HTML5/GSAP/TweenMax/time/),
[timeScale](http://greensock.com/docs/#/HTML5/GSAP/TweenMax/timeScale/),
[totalDuration](http://greensock.com/docs/#/HTML5/GSAP/TweenMax/totalDuration/)\*,
[totalProgress](http://greensock.com/docs/#/HTML5/GSAP/TweenMax/totalProgress/)\*,
[totalTime](http://greensock.com/docs/#/HTML5/GSAP/TweenMax/totalTime/)\*,

*For TimelineMax and TimelineLite:*  
> [currentLabel](http://greensock.com/docs/#/HTML5/GSAP/TimelineMax/currentLabel/),
[duration](http://greensock.com/docs/#/HTML5/GSAP/TimelineMax/duration/)\*,
[endTime](http://greensock.com/docs/#/HTML5/GSAP/TimelineMax/endTime/)\*,
[eventCallback](http://greensock.com/docs/#/HTML5/GSAP/TimelineMax/eventCallback/),
[from](http://greensock.com/docs/#/HTML5/GSAP/TimelineMax/from/),
[fromTo](http://greensock.com/docs/#/HTML5/GSAP/TimelineMax/fromTo/),
[getLabelAfter](http://greensock.com/docs/#/HTML5/GSAP/TimelineMax/getLabelAfter/),
[getLabelBefore](http://greensock.com/docs/#/HTML5/GSAP/TimelineMax/getLabelBefore/),
[getLabelArray](http://greensock.com/docs/#/HTML5/GSAP/TimelineMax/getLabelArray/),
[getLabelTime](http://greensock.com/docs/#/HTML5/GSAP/TimelineMax/getLabelTime/),
[invalidate](http://greensock.com/docs/#/HTML5/GSAP/TimelineMax/invalidate/),
[isActive](http://greensock.com/docs/#/HTML5/GSAP/TimelineMax/isActive/),
[pause](http://greensock.com/docs/#/HTML5/GSAP/TimelineMax/pause/),
[paused](http://greensock.com/docs/#/HTML5/GSAP/TimelineMax/paused/),
[play](http://greensock.com/docs/#/HTML5/GSAP/TimelineMax/play/),
[progress](http://greensock.com/docs/#/HTML5/GSAP/TimelineMax/progress/),
[restart](http://greensock.com/docs/#/HTML5/GSAP/TimelineMax/restart/),
[resume](http://greensock.com/docs/#/HTML5/GSAP/TimelineMax/resume/),
[reverse](http://greensock.com/docs/#/HTML5/GSAP/TimelineMax/reverse/),
[reversed](http://greensock.com/docs/#/HTML5/GSAP/TimelineMax/reversed/),
[seek](http://greensock.com/docs/#/HTML5/GSAP/TimelineMax/seek/),
[startTime](http://greensock.com/docs/#/HTML5/GSAP/TimelineMax/startTime/)\*,
[time](http://greensock.com/docs/#/HTML5/GSAP/TimelineMax/time/),
[timeScale](http://greensock.com/docs/#/HTML5/GSAP/TimelineMax/timeScale/),
[totalDuration](http://greensock.com/docs/#/HTML5/GSAP/TimelineMax/totalDuration/)\*,
[totalProgress](http://greensock.com/docs/#/HTML5/GSAP/TimelineMax/totalProgress/)\*,
[totalTime](http://greensock.com/docs/#/HTML5/GSAP/TimelineMax/totalTime/)\*,
[tweenFromTo](http://greensock.com/docs/#/HTML5/GSAP/TimelineMax/tweenFromTo/),
[tweenTo](http://greensock.com/docs/#/HTML5/GSAP/TimelineMax/tweenTo/),

**Notes:**
  - Some of the methods above aren't available for TweenLite and TimelineLite. Please check the GSAP docs for more details.
  - 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](#animationsource) function while you construct the animation.

***\**** Through the controller, you can only get values with these methods.

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

##### ```animationSource```
 - ```({target, options}) -> GSAP Animation```

A function that returns a GSAP Animation.
```javascript
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](#selector).
 - ```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
```javascript
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](#methods-added-to-the-component) call as the second argument and will be passed to the [animationSource](#animationsource)
```javascript
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, i.e. ```{key: 'head'}```, ```{color: 'red'}```, and ```{key: 'head', color:  'red}``` are all matches to ```<div key='head' color='red'/>```.

I'm looking forward to your feedback!

[react-motion]: https://github.com/chenglou/react-motion
[Animated]: https://facebook.github.io/react-native/docs/animations.html#animated
[GSAP]: http://greensock.com/
[React]: https://github.com/facebook/react
[react-npm]: https://www.npmjs.com/package/react
[gsap-npm]: https://www.npmjs.com/package/gsap
[gsap-cdn]: https://cdnjs.com/libraries/gsap