Introduction to Popmotion: Custom Animation Scrubber

In the first part of the Popmotion introductory series, we learned how to use time-based animations like tween and keyframes. We also learned how to use those animations on the DOM, using the performant styler.

In part two, we learned how to use pointer tracking and record velocity. We then used that to power the velocity-based animations spring, decay, and physics.

In this final part, we’re going to be creating a scrubber widget, and we’re going to use it to scrub a keyframes animation. We’ll make the widget itself from a combination of pointer tracking as well as spring and decay to give it a more visceral feel than run-of-the-mill scrubbers.

Try it for yourself:

Getting Started

Markup

First, fork this CodePen for the HTML template. As before, because this is an intermediate tutorial, I won’t go through everything.

The main twist of note is that the handle on the scrubber is made up of two div elements: .handle and .handle-hit-area.

.handle is the round blue visual indicator of where the scrubber handle is. We’ve wrapped it in an invisible hit area element to make grabbing the element easier for touchscreen users.

Import Functions

At the top of your JS panel, import everything we’re going to use in this tutorial:

const { easing, keyframes, pointer, decay, spring, styler, transform, listen, value } = popmotion;
const { pipe, clamp, conditional, linearSpring, interpolate } = transform;

Select Elements

We’re going to need three elements in this tutorial. We’ll animate the .box, drag and animate the .handle-hit-area, and measure the .range.

Let’s also create stylers for the elements we’re going to animate:

const box = document.querySelector('.box');
const boxStyler = styler(box);

const handle = document.querySelector('.handle-hit-area');
const handleStyler = styler(handle);

const range = document.querySelector('.range');

Keyframes Animation

For our scrubbable animation, we’re going to make the .box move from left to right with keyframes. However, we could just as easily scrub a tween or timeline animation using the same method outlined later in this tutorial.

const boxAnimation = keyframes({
  values: [0, -150, 150, 0],
  easings: [easing.backOut, easing.backOut, easing.easeOut],
  duration: 2000
}).start(boxStyler.set('x'));

Your animation will now be playing. But we don’t want that! Let’s pause it for now:

boxAnimation.pause();

Dragging the x-axis

It’s time to use pointer to drag our scrubber handle. In the previous tutorial, we used both x and y properties, but with a scrubber we only need x.

We prefer to keep our code reusable, and tracking a single pointer axis is quite a common use case. So let’s create a new function called, imaginatively, pointerX.

It will work exactly like pointer except it’ll take just a single number as its argument and output just a single number (x):

const pointerX = (x) => pointer({ x }).pipe(xy => xy.x); 

Here, you can see we’re using a method of pointer called pipe. pipe is available on all the Popmotion actions we’ve seen so far, including keyframes.

pipe accepts multiple functions. When the action is started, all output will be passed through each of these functions in turn, before the update function provided to start fires.

In this case, our function is simply:

xy => xy.x

All it is doing is taking the { x, y } object usually output by pointer and returning just the x axis.

Event Listeners

We need to know if the user has started pressing the handle before we start tracking with our new pointerX function.

In the last tutorial we used the traditional addEventListener function. This time, we’re going to use another Popmotion function called listen. listen also provides a pipe method, as well as access to all action methods, but we’re not going to use that here.

listen allows us to add event listeners to multiple events with a single function, similar to jQuery. So we can condense the previous four event listeners to two:

listen(handle, 'mousedown touchstart').start(startDrag);
listen(document, 'mouseup touchend').start(stopDrag);

Move the Handle

We’ll be needing the handle’s x velocity later on, so let’s make it a value, which as we learned in the last tutorial allows us to query velocity. On the line after we define handleStyler, add:

const handleX = value(0, handleStyler.set('x'));

Now we can add our startDrag and stopDrag functions:

const startDrag = () => pointerX(handleX.get())
  .start(handleX);
  
const stopDrag = () => handleX.stop();

Right now, the handle can be scrubbed beyond the boundaries of the slider, but we’ll come back to this later.

Scrubbing

Now we have a visually functional scrubber, but we’re not scrubbing the actual animation.

Every value has a subscribe method. This allows us to attach multiple subscribers to fire when the value changes. We want to seek the keyframes animation whenever handleX updates.

First, measure the slider. On the line after we define range, add:

const rangeWidth = range.getBoundingClientRect().width;

keyframes.seek accepts a progress value as expressed from 0 to 1, whereas our handleX is set with pixel values from 0 to rangeWidth.

We can convert from the pixel measurement to a 0 to 1 range by dividing the current pixel measurement by rangeWidth. On the line after boxAnimation.pause(), add this subscribe method:

handleX.subscribe(v => boxAnimation.seek(v / rangeWidth));

Now, if you play with the scrubber, the animation will scrub successfully!

The Extra Mile

Spring Boundaries

The scrubber can still be pulled outside the boundaries of the full range. To solve this, we could simply use a clamp function to ensure we don’t output values outside of 0, rangeWidth.

Instead, we’re going to go the extra step and attach springs to the end of our slider. When a user pulls the handle beyond the permitted range, it will tug back towards it. If the user releases the handle while it’s outside the range, we can use a spring animation to snap it back.

We’ll make this process a single function that we can provide to the pointerX pipe method. By creating a single, reusable function, we can reuse this piece of code with any Popmotion animation, with configurable ranges and spring strengths.

First, let’s apply a spring to the left-most limit. We’ll use two transformers, conditional and linearSpring.

const springRange = (min, max, strength) => conditional(
  v => v < min,
  linearSpring(strength, min)
);

conditional takes two functions, an assertion and a transformer. The assertion receives the provided value and returns either true or false. If it returns true, the second function will be provided the value to transform and return.

In this case, the assertion is saying, "If the provided value is smaller than min, pass this value through the linearSpring transformer." The linearSpring is a simple spring function that, unlike the physics or spring animations, has no concept of time. Provide it a strength and a target, and it will create a function that "attracts" any given value towards the target with the defined strength.

Replace our startDrag function with this:

const startDrag = () => pointerX(handleX.get())
  .pipe(springRange(0, rangeWidth, 0.1))
  .start(handleX);

We're now passing the pointer's x offset through our springRange function, so if you drag the handle past the left-most side, you'll notice it tugs back.

Applying the same to the right-most side is a matter of composing a second conditional with the first using the stand-alone pipe function:

const springRange = (min, max, strength) => pipe(
  conditional(
    v => v < min,
    linearSpring(strength, min)
  ),
  conditional(
    v => v > max,
    linearSpring(strength, max)
  )
);

Another benefit of composing a function like springRange is that it becomes very testable. The function it returns is, like all transformers, a pure function that takes a single value. You can test this function to see if it passes through values that lie within min and max unaltered, and if it applies springs to values that lie without.

If you let go of the handle while it lies outside the range, it should now spring back to within range. For that, we'll need to adjust the stopDrag function to fire a spring animation:

const stopDrag = () => {
  const x = handleX.get();
  (x < 0 || x > rangeWidth)
    ? snapHandleToEnd(x)
    : handleX.stop();
};

Our snapHandleToEnd function looks like this:

const snapHandleToEnd = (x) => spring({
  from: x,
  velocity: handleX.getVelocity(),
  to: x < 0 ? 0 : rangeWidth,
  damping: 30,
  stiffness: 5000
}).start(handleX);

You can see that to is set either as 0 or rangeWidth depending on which side of the slider the handle currently sits. By playing with damping and stiffness, you can play with a range of different spring-feels.

Momentum Scrolling

A nice touch on iOS scrubber that I always appreciated was that if you threw the handle, it would gradually slow down rather than come to a dead stop. We can replicate that easily using the decay animation.

In stopDrag, replace handleX.stop() with momentumScroll(x).

Then, on the line after the snapHandleToEnd function, add a new function called momentumScroll:

const momentumScroll = (x) => decay({
  from: x,
  velocity: handleX.getVelocity()
}).start(handleX);

Now, if you throw the handle, it will come to a gradual stop. It will also animate outside the range of the slider. We can stop this by passing the clamp transformer to the decay.pipe method:

const momentumScroll = (x) => decay({
  from: x,
  velocity: handleX.getVelocity()
}).pipe(clamp(0, rangeWidth))
  .start(handleX);

Conclusion

Using a combination of different Popmotion functions, we can create a scrubber that has a bit more life and playfulness than the usual.

By using pipe, we compose simple pure functions into more complex behaviours while leaving the composite pieces testable and reusable.

Next Steps

How about trying these challenges:

• Make the momentum scroll end with a bounce if the handle hits either end of the scrubber.
• Make the handle animate to any point on the scrubber when a user clicks on another part of the range bar.
• Add full play controls, like a play/pause button. Update the scrubber handle position as the animation progresses.