Guide

Scrollex is a react library that lets you build beautiful scroll experiences using minimal code.

If you want to install scrollex in your own react project, you can do so with npm or yarn.

However for this guide, scrollex is pre-installed in the sandbox to the right and all you have to do is read, scroll, and observe.

To get started with scrollex, we need to add a Scroll.Container to hold all of our scrollable content.

In many cases we'll want the container to take up the full size of the viewport, however it can be any size.

Next we'll partition our content in to different sections.

This will give us access to important keyframes as we're scrolling through the container's content.

For example we might want to define some condition to be true when the top of a section is in line with the top of the container.

At this point, you'll notice we just have a static page with no motion. In general we recommend first building the static layout, and then adding motion where you see fit.

So let's go ahead and add some motion to the example.

What we'd like to do is produce an effect where the headings slide in and then slide out as we scroll by.

To do this we'll use the Scroll.Item component and pass it some keyframes.

These keyframes define how an element should look as the user scrolls through the content.

The code above dictates that before the user has scrolled at all, headings should have a translation of -200px along the x axis.

However it also dictates that after the user has scrolled down an amount of 200 pixels, then each heading should have a translation of +200 pixels along the x axis.

So then you might be wondering what will the translation be when the user has scrolled down 100 pixels from the top?

Well it turns out it will be 0 pixels because scrollex uses linear interpolation to transition between keyframes.

The effect we have right now is not particulary pleasant because each heading is already done animating after we've scrolled 200px.

What we'd rather do is have each heading wait to begin animating until it becomes visible on the screen.

Thankfully scrollex provides some keyframe helpers that allow us identify important keyframes as we're scrolling.

As you can see, keyframes can either be a keyframes object or, in this case, a keyframes function that returns the keyframes object.

With the above change, each heading will begin animating only after we scroll down to its containing section.

Here section.topAt("container-bottom") will return the number of pixels the user has to scroll for the top edge of the section to intersect the bottom edge of the container.

Likewise section.bottomAt("container-top") will return the number of pixels the user has to scroll for the bottom edge of the section to intersect the top edge of the container.

But how do we know which section we're dealing with?

Well Scroll.Item can only be used within Scroll.Section, so the keyframes function passed to a Scroll.Item will always reference the item's containing section.

The cool thing about this is that scrollex is tracking the section bounds internally and if the section's size/position happen to change, scrollex will automatically recalculate our keyframes!

At the moment our headings move at a constant speed across the screen while we scroll, but what if we wanted them to move in quickly, then stick in the center for a bit, and then move out quickly?

We can do this by adding two more keyframes in between our existing keyframes.

In the code above, the first and last keyframe are identical to those in the previous step, however now we've added two keyframes in between which guarantee that the heading will remain centered for a range of 200 pixels as we scroll by.

Because section.topAt("container-top") returns a scroll offset value in pixels, we can easily add or subtract pixels from it to fine-tune our experience.

Not only can we add/subtract values like 100, but we can do arithmetic like the following to create a more responsive experience.

But why stop there?

We can actually use container/section dimensions within our transforms.

With this we're guaranteed that no matter the screen size, our headings will always begin offscreen to the left and finish offscreen to the right.

Wrapping Up

We hope this guide has been helpful and we encourage you to check out the api reference and the examples to see more of what's possible with scrollex!