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?


Failed to load latest commit information.
Latest commit message
Commit time
September 23, 2023 20:38
April 10, 2023 11:11
June 21, 2023 15:36
April 16, 2023 20:42
September 23, 2023 20:38
September 23, 2023 20:38
April 9, 2023 12:10
April 20, 2023 14:40
August 15, 2023 11:48
April 14, 2023 16:58
April 29, 2023 10:49
July 19, 2023 10:09
April 11, 2023 18:01
September 17, 2023 01:15

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

👇 New documentation here! 👇


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:



"My simple animation is not doing anything on scroll"

Please check your start and end values for your Root component. A typical issue comes when:

  1. your animation "starts when the start of the scroller hits the start of the viewport",
  2. your animation "ends when the bottom of the scroller hits the bottom of the viewport",
  3. the element your Root wraps around is only 100vh tall, so the animation's duration is 0.

To fix this, either add more height to the element your Root wraps, or tweak the end value to be something like bottom start, which would mean "when the bottom of the scroller hits the start of the viewport".

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