Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time
April 28, 2023 16:03
April 10, 2023 11:11
June 6, 2023 11:09
April 16, 2023 20:42
June 6, 2023 11:05
June 6, 2023 11:09
April 9, 2023 12:10
April 20, 2023 14:40
April 9, 2023 12:10
April 14, 2023 16:58
April 29, 2023 10:49
April 29, 2023 10:49
April 11, 2023 18:01
April 9, 2023 12:10
April 21, 2023 07:32

BSMNT Scrollytelling

BSMNT Scrollytelling is a library for creating Scrollytelling animations. It's powered by GSAP ScrollTrigger, but abstracts away some things to make it work better with React.

Frame 7


To get started, we'll need the @bsmnt/scrollytelling package, as well as the required peer dependency: GSAP.

yarn add @bsmnt/scrollytelling gsap


At basement, we've built a bunch of websites that use scroll animations. Over the years, we faced some issues that required solutions that we copy-pased throughout different project. While preparing his talk for the React Miami Conference, JB decided to build a library to share how we build these with the world.

Challenges we faced

  • Needed a deep understanding of how GSAP works with ScrollTrigger.
  • Needed to be careful about running animations inside useEffect and then cleaning them up.
  • Couldn’t think of scroll animations in terms of a start and an end, so it was hard to fire up animations at the exact scroll progress we needed to.


We aimed at componentizing a way of building scroll animations that could:

  • Provide sensible defaults for scroll animations, such as scrub: true, and ease: 'linear'.
  • Take care of component mounting and unmounting.
  • Create animations with absolute positioning defined by a start and an end, instead of a time-based duration.

As an added benefit, going "component-based" allowed us to:

  • Improve compatibility with React Server Components: our components definitely 'use client', but not necessarily the parents or children of our components.
  • Compose animations at every level of the tree, as it all works with React Context.

A simple example of how this works:

117 (1)


  • Root: Creates timeline and scrollTrigger, provides React Context.
  • Animation: Appends an animation to the timeline. Receives a tween prop that will control how the animation behaves.
  • Waypoint: Runs a callback or tween at a specific point in the timeline. Can also receive a label prop, that will create a GSAP label at that position.
  • RegisterGsapPlugins: Registers custom GSAP plugins, if you need them for a specific use case.
  • Parallax: Helper to create a simple parallax.
  • ImageSequenceCanvas: Helper to create a simple image sequence animation.
  • useScrollytelling: Context consumer. Returns the timeline.
  • useScrollToLabel: Scrolls to the label name you pass. Labels can be added with the Waypoint component.


For our talk at React Miami Conf, we did a small demo to showcase this library in action. This is the best place to see how the library works in a real world scenario. Check it out:


GSAP files are subject to GreenSock's standard license which can be found at