# react-gsap: declarative GSAP animations in React

> react-gsap is a TypeScript wrapper that lets you drive GSAP tweens and timelines from React components instead of calling the animation functions directly, and it ships plugins and helper components alongside the wrappers. It suits projects that want the declarative style, and the maintainer states plainly that it has not been updated in some time and does not use the newest GSAP APIs.

**bitworking/react-gsap** — React components for GSAP

- Repository: https://github.com/bitworking/react-gsap
- Website: https://bitworking.github.io/react-gsap/
- Stars: 665 · Forks: 32
- Language: TypeScript
- License: NOASSERTION
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/bitworking-react-gsap

## A wrapper that hides the Tween and Timeline calls

react-gsap lets you use the GreenSock Animation Platform in React in a fully declarative way. The specific thing it abstracts away is direct use of the GSAP Tween and Timeline functions, which is exactly the part of GSAP that fights with a component model. In plain GSAP you create a tween, you point it at a target, and you keep the reference so you can reverse or clean it up. In React you want to describe what should happen for a given set of props and let the framework reconcile it.

The library is not a replacement for GSAP. The README says plainly that react-gsap just adds some React wrapper components for these functions, and that you should read the official GreenSock documentation to know how to do things. GSAP itself is a set of JavaScript functions that let you tween a value, an attribute or a CSS property over time and insert those tweens into a timeline for more complex animations.

What the wrapper adds on top is a set of components plus a small amount of shipped GSAP plugins and useful helper components. And the escape hatch matters: if you need full control, it is possible to get low level access to the underlying objects. That combination, a declarative surface with an imperative escape route, is the design that has kept the library usable in the presence of the caution at the top of the README.

The package is written in TypeScript and ships the types directly, so there is no separate type package to install. The documentation and examples live at bitworking.github.io/react-gsap, and the examples on the documentation pages are editable directly in the browser, which is a genuinely useful way to evaluate a wrapper library before committing to it.

## A monorepo with a single peer dependency

The repository layout is small and tells you a few things. The top level contains a package.json, a yarn.lock, an eslint configuration, a prettier configuration and a packages/ directory, and the root package.json is a private workspace root:

```json
{
  "private": true,
  "workspaces": [
    "packages/*"
  ]
}
```

So the published library lives under packages/ and the repository is managed with yarn workspaces rather than with lerna or a single flat package. The presence of yarn.lock alongside npm instructions in the README is worth noticing, since a contributor and a consumer use different package managers here.

The dependency design is the part that matters for a consumer. From version 2 the library is built for GSAP 3 and has only gsap as a peer dependency, and the README explains the reason: in this way you can update gsap separately from react-gsap. That is a deliberate decoupling, and it is the difference between a wrapper that pins you to a specific animation library version and one that lets the animation library move on its own schedule.

Given that the last published version of react-gsap is from 2021, that separation is the only reason the package can still be installed in a modern project at all. If the animation library were vendored, the wrapper would be frozen at 2021 GSAP behaviour by construction. The cost of the decoupling is the opposite one, that the wrapper has to be re-checked whenever GSAP changes, and by the maintainer's own account it has not been.

The npm package itself publishes types, has a bundle size badge on the npm registry page, and offers an MIT licence in the README.

## The caution at the top of the README, read literally

The README leads with a caution block, and it is the most important paragraph in the project.

The maintainer states that this library has not been updated in quite some time. It should work with React 19 if you ignore the package warnings, but it does not use the latest GSAP APIs, particularly gsap.context(). There is now also a useGSAP hook available directly from GSAP, which you might want to consider if you do not need a strictly declarative approach. And the maintainer invites you to contact them if you want to work on the next version, which uses all modern features of GSAP.

Four separate claims, and they point in different directions. The React 19 statement is a qualified yes, conditional on muting warnings, which is a real cost in a project that treats console warnings as failures in CI. The gsap.context() gap is a functional one, since context is the mechanism GSAP provides for scoping animations to a component and cleaning them up, and a wrapper that predates it cannot offer that pattern. The useGSAP suggestion is the maintainer pointing at the alternative and saying it may be the better fit. The invitation to contact them is a signal that the next version is contingent on someone doing the work, on top of whatever else they are doing.

The release history matches that account. The three most recent tags are v3.1.0, v3.2.0 and v3.2.1, all in the first week of April 2021, while the repository itself received a push on 2026-05-09. The source tree is being touched, but no new version has been published to npm since 2021.

That gap between the repository and the registry is the practical thing to hold on to. A green build in your project depends on the published 3.2.1 artefact, not on whatever is in the master branch.

## When useGSAP is the better answer

The alternative named in the README is a hook that GSAP now ships directly, and it is worth understanding why the maintainer points at it, because it is not a like for like swap.

react-gsap gives you components that describe a tween or a timeline as part of the render tree. The declarative model means the animation is a function of props, and the library handles creating and reverting tweens as the component's state changes. That is the appeal for a team that wants animation to look like the rest of their React markup.

A hook gives you the animation in a component effect instead. The tween is created imperatively, inside your own lifecycle, so you control when it starts, when it reverses, and when it is cleaned up. It is not declarative in the component-tree sense, and the maintainer is explicit that this is the trade: consider it if you do not need a strictly declarative approach.

The concrete difference is ownership of cleanup. gsap.context() exists to scope a set of animations to a component so they can be reverted or killed together, and the README says this library does not use it. So with react-gsap you are on an older cleanup model, and with the GSAP hook you are on the current one, in your own code where you can see it.

The right choice depends on the shape of the work. A marketing site with a lot of scroll-driven and staged animation is the case where a declarative wrapper earns its keep. A component library with a handful of well-understood transitions, especially one that already has a cleanup story, is the case where the maintainer is right that the GSAP hook is simpler.

## Installing it and playing with the editable examples

Installation is a single command, and it installs both packages because GSAP is a peer dependency:

```bash
npm install gsap react-gsap
```

What you should see after that is a working import of the wrapper components in a React project, with TypeScript types resolving from the same package rather than from a separate @types entry. There is no provider to mount, no plugin registration step, and no configuration file, which is the practical benefit of the wrapper approach.

Before you write any of your own code, the documentation site is the better first stop. The README states that the examples on the documentation pages are all editable directly in the browser, and invites you to play with them. For a library whose main risk is version drift against GSAP, evaluating against live examples that you can modify is more informative than reading prose, and it lets you check the behaviour of the GSAP version currently published rather than the one from 2021.

Two practical warnings to carry into that session. If your build treats peer dependency warnings as errors, you will hit the React 19 warning the maintainer mentions, and you have to decide explicitly whether to suppress it. And if you need animations scoped to a component with gsap.context(), the wrapper will not give you that, so prototype that part with the GSAP hook instead and see whether you still need the wrapper at all.

## Where react-gsap is the wrong tool

The clearest case is a greenfield project. If you are starting a new React application in 2026 and want GSAP, the maintainer has told you that GSAP itself now ships a hook for this, and that the wrapper has not been updated in some time. Starting new work on a package whose newest published version is 3.2.1 from 2021, with a known gap around gsap.context(), is a decision you should be able to justify.

The second case is a team that has standardised on the GSAP hook. If your codebase already uses the hook everywhere, adding a second animation abstraction means two patterns to learn, two cleanup models to reason about, and a wrapper that lags the library underneath it. Consistency is worth more than the declarative convenience in that situation.

The third is the licence question. The GitHub licence field for the repository is one the platform cannot classify, pointing at the LICENSE file, while the README states MIT with a copyright line naming bitworking. Those two statements do not obviously agree, and the LICENSE file is what settles it. This article does not interpret it, but a wrapper library that you are likely to copy into a commercial product is precisely the case where you read the file rather than the badge.

The last point is about the repository itself. The master branch received a push on 2026-05-09, and there is no GitHub release newer than 3.2.1 from 2021, so the code in the tree and the code you install are different things. If you are evaluating this for a long-lived product, the sensible check is to look at what changed in the repository since the last published version, and to read the maintainer's note about what a next version would involve, since they have said that work on it needs to be arranged.

## Conclusion

Adopt react-gsap if you are on React and want a declarative style for GSAP, you are comfortable with a package whose published versions date from 2021, and you need the wrapper components rather than the imperative API. Do not adopt it for a new project that can start from the useGSAP hook that GSAP now ships directly, since the maintainer points there himself, and do not rely on it for gsap.context() behaviour. Verify first that the peer dependency setup works in your build, that the documented examples run against the GSAP version you intend to pin, and that the licence terms are the MIT ones the README states rather than the unclassified licence GitHub reports for the project, because the last push was on 2026-05-09 and the newest published version is 3.2.1 from 2021.

## FAQ

### How do I install react-gsap?

The README gives npm install gsap react-gsap, installing GSAP alongside it because from version 2 the library is built for GSAP 3 and has gsap as its only peer dependency, so gsap can be updated separately from react-gsap.

### Does react-gsap work with React 19?

The README says it should work with React 19 if you ignore the package warnings, and that the library has not been updated in quite some time and does not use the latest GSAP APIs, particularly gsap.context().

### What is the difference between react-gsap and the useGSAP hook?

react-gsap provides declarative React wrapper components around the GSAP Tween and Timeline functions, while GSAP now ships a useGSAP hook directly. The maintainer suggests considering the hook if you do not need a strictly declarative approach, and invites contact for work on a next version of the library that uses modern GSAP features.

### What licence is react-gsap released under?

The README states MIT with a copyright line naming bitworking, while the GitHub licence field for the repository is one the platform cannot classify and points at the LICENSE file. The last push was on 2026-05-09, and the newest published version is 3.2.1 from 2021-04-08.

## Sources

- [bitworking/react-gsap on GitHub](https://github.com/bitworking/react-gsap)
- [Issues](https://github.com/bitworking/react-gsap/issues)
- [Project website](https://bitworking.github.io/react-gsap/)
- [README](https://github.com/bitworking/react-gsap/blob/master/README.md)
- [Releases](https://github.com/bitworking/react-gsap/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/bitworking-react-gsap