Spring

Matt Perry

In this tutorial, we're going to build the Spring example step-by-step.

This tutorial is rated beginner difficulty, which means we'll spend some time explaining the Motion APIs that we've chosen to use (and why), and also any browser APIs we encounter that might be unfamiliar to beginners.

Here's a live demo of the example we're going to be creating:

Introduction

The Spring example shows how to create smooth, physics-based animations using Motion's animate function with spring animations. Spring animations feel more natural than traditional tween animations because they simulate real-world physics, creating organic motion that responds to changes with realistic momentum and bounce.

Instead of manually calculating velocities, damping, and stiffness values, you simply set type: "spring" in your animation options, and Motion handles all the physics for you.

Get started

Let's start with a simple HTML structure and styling:

<div class="box"></div>

<script type="module">
</script>

<style>
    .box {
        width: 100px;
        height: 100px;
        background-color: #ff0088;
        border-radius: 10px;
    }
</style>

This creates a pink square with rounded corners that we'll animate.

Let's animate!

Import from Motion

First, import the animate function from Motion:

<script type="module">
    import { animate } from "motion"
</script>

Add the spring animation

Now we can animate the box with a spring animation. Add this inside the script tag:

animate(
    ".box",
    { rotate: 90 },
    { type: "spring" }
)

The animate function takes three arguments:

Target - A CSS selector (.box) or DOM element to animate
Values - An object defining what to animate ({ rotate: 90 })
Options - Configuration for how the animation behaves

By setting type: "spring", Motion uses physics-based motion instead of a linear or eased transition. This creates a more natural feel with realistic overshoot and settling.

Make it loop

To see the spring animation repeat, add the repeat and repeatDelay options:

animate(
    ".box",
    { rotate: 90 },
    { type: "spring", repeat: Infinity, repeatDelay: 0.2 }
)

The repeat: Infinity option makes the animation loop forever, while repeatDelay: 0.4 adds a brief pause between each rotation. This gives you time to appreciate how the spring physics naturally settles into place before starting again.

Customizing spring physics

Motion provides two ways to configure spring behavior. The first uses physics-based parameters:

animate(
    ".box",
    { rotate: 90 },
    {
        type: "spring",
        stiffness: 100,
        damping: 10,
        mass: 1,
    }
)

stiffness - Controls how rigid the spring feels. Higher values create faster, snappier motion. Default is 100.
damping - Controls how quickly the spring settles. Lower values create more oscillation. Default is 10.
mass - The mass of the moving object. Higher values create slower, more lumbering motion. Default is 1.

The second approach uses duration and bounce, which is often more intuitive:

animate(
    ".box",
    { rotate: 90 },
    {
        type: "spring",
        duration: 0.8,
        bounce: 0.25,
    }
)

duration - How long the animation takes to settle, in seconds.
bounce - A value between 0 and 1 controlling how much the spring overshoots. A value of 0 creates no bounce (like a critically damped spring), while higher values create more oscillation.

The duration/bounce API is useful when you need predictable timing, while the physics parameters give you finer control over the feel of the motion.

Conclusion

We've built a simple but effective spring animation that demonstrates physics-based motion. Spring animations are perfect for UI interactions because they feel responsive and natural.