# How to Configure Spring Animations Using Traditional Physics Parameters in Motion

> Configure spring animations using mass stiffness and damping for precise UI motion control. Learn to manipulate physical properties for advanced animation effects.

- Repository: [Emil Kowalski/skills](https://github.com/emilkowalski/skills)
- Tags: how-to-guide
- Published: 2026-08-06

---

Spring animations using **mass**, **stiffness**, and **damping** give you precise control over UI motion by directly manipulating physical properties rather than relying on higher-level timing abstractions.

In the **emilkowalski/skills** repository, the Motion (formerly Framer Motion) library supports two distinct configuration styles: Apple-style springs (`duration` + `bounce`) and traditional physics springs (`mass` + `stiffness` + `damping`). This guide focuses on the latter—when you need granular control over how an element settles into place.

## Core Physics Parameters

The three parameters that define a traditional physics spring are:

| Parameter | Physical Meaning | Typical Value in Repository |
|-----------|----------------|-----------------------------|
| **mass** | Inertia of the animated object—higher values feel heavier and slower | `1` (default) |
| **stiffness** | Force pulling toward the target—higher values produce snappier motion | `100` |
| **damping** | Resistance that kills oscillations—lower values create more bounce | `10` |

These values appear together in [`skills/animate/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/animate/SKILL.md) as the canonical traditional-physics example:

```typescript
{
  type: "spring",
  mass: 1,
  stiffness: 100,
  damping: 10
}

```

According to the source at `skills/animate/SKILL.md#L129-L130`, this configuration produces a critically damped spring—smooth settling without overshoot.

## Traditional Physics vs. Apple-Style Springs

The repository treats both approaches as first-class configurations, but they serve different purposes.

**Traditional physics** (`mass` / `stiffness` / `damping`) excels when you need to tune the *feel* of an interaction. Designers can independently adjust:
- How heavy the object feels (mass)
- How aggressively it snaps to target (stiffness)
- How quickly it stops oscillating (damping)

**Apple-style** (`duration` / `bounce`) trades expressiveness for predictability. As noted in `skills/review-animations/STANDARDS.md#L67-L70`, Apple-style configurations use `duration: 0.5` and `bounce` values to match platform conventions without requiring physics intuition.

Choose traditional physics when gesture-driven elements need customized settling behavior; prefer Apple-style for standard transitions that must align with system conventions.

## Basic Traditional Physics Configuration

Here's the standard implementation following repository conventions:

```typescript
import { motion } from "motion";

motion(
  element,
  { y: targetY, opacity: 1 },
  {
    type: "spring",
    mass: 1,
    stiffness: 100,
    damping: 10
  }
);

```

Notice that `duration` is **omitted**—the animation length emerges naturally from the physics values. A stiffer spring with lighter mass completes faster; heavier mass or higher damping extends the settle time.

## Handling Gesture Release Velocity

For interruptible, momentum-preserving animations, pass the gesture velocity directly to the spring configuration. The `skills/apple-design/SKILL.md#L104-L110` section demonstrates this pattern for drag gestures:

```typescript
function onDragEnd(event, info) {
  const velocityY = info.velocity.y; // pixels per second from pointer

  motion(
    element,
    { y: snapTargetY },
    {
      type: "spring",
      mass: 1,
      stiffness: 100,
      damping: 10,
      velocity: velocityY // preserves throw momentum
    }
  );
}

```

The `velocity` parameter accepts raw pixel-per-second values from Motion's gesture system. Without this, the spring restarts from zero velocity, breaking the illusion of physical continuity.

## Tuning Parameters for Different Feels

Adjust the three core parameters to achieve specific motion characteristics:

- **Heavy, sluggish feel**: Increase `mass` to `2` or higher
- **Snappy, responsive snap**: Increase `stiffness` to `300+`
- **Bouncy, playful settling**: Decrease `damping` to `5` or below
- **Smooth, professional stop**: Keep `damping` near `10` for critical damping

The `skills/animation-vocabulary/SKILL.md#L126-L132` glossary defines these terms for cross-functional teams, ensuring designers and developers share the same mental model.

## Enforcing Consistency via Repository Standards

The `skills/review-animations/STANDARDS.md#L67-L70` file contains authoritative tables of approved spring configurations. The `skills/improve-animations/AUDIT.md#L65-L66` rules require reviewers to pull exact values from these tables rather than inventing custom numbers.

When submitting code, reference the specific standard you're following:

```typescript
// Matches skills/review-animations/STANDARDS.md physics-style #1
const springConfig = {
  type: "spring",
  mass: 1,
  stiffness: 100,
  damping: 10
};

```

This practice guarantees that all spring animations in the codebase feel coherent and maintainable.

## Complete Responsive Example

Here's a pattern that switches between physics styles based on design tokens:

```typescript
import { motion } from "motion";

interface SpringOptions {
  isPlayful: boolean;
  gestureVelocity?: number;
}

function animateToTarget(
  element: Element,
  target: { x: number; y: number },
  options: SpringOptions
) {
  const { isPlayful, gestureVelocity = 0 } = options;

  const config = isPlayful
    ? { type: "spring" as const, duration: 0.5, bounce: 0.2 }
    : { type: "spring" as const, mass: 1, stiffness: 100, damping: 10 };

  motion(element, target, {
    ...config,
    ...(gestureVelocity !== 0 && { velocity: gestureVelocity })
  });
}

```

This mirrors the conditional pattern shown in [`skills/animate/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/animate/SKILL.md), accommodating both precise tool interactions and playful marketing moments within the same component.

## Summary

- **Use `mass`, `stiffness`, and `damping`** when you need fine-grained control over spring behavior
- **Reference [`STANDARDS.md`](https://github.com/emilkowalski/skills/blob/main/STANDARDS.md)** for approved parameter combinations rather than guessing values
- **Pass `velocity` from gestures** to maintain momentum across animation interruptions
- **Omit `duration`** for physics springs—the settle time derives naturally from the parameters
- **Document your config source** in code comments to satisfy audit requirements

## Frequently Asked Questions

### What happens if I specify both duration and physics parameters?

Motion prioritizes the physics model when `mass`, `stiffness`, or `damping` are present, ignoring `duration`. For time-based control, switch to Apple-style configuration with `duration` and `bounce` instead.

### How do I convert between Apple-style and traditional physics values?

The repository does not provide automatic conversion—[`STANDARDS.md`](https://github.com/emilkowalski/skills/blob/main/STANDARDS.md) maintains separate tables for each style. As a rule of thumb, `duration: 0.5, bounce: 0` approximates `mass: 1, stiffness: 100, damping: 10`, but subtle differences in feel remain.

### Can I animate stiffness or damping mid-animation?

No—Motion evaluates spring parameters once at animation start. For dynamic behavior, interrupt the current animation with a new `motion()` call using updated parameters and the current velocity.

### Why does my spring feel different on 120Hz displays?

Motion's physics solver uses wall-clock time, so the same parameters produce consistent settle durations regardless of refresh rate. If perception differs, verify that you're not inadvertently scaling time elsewhere in your animation pipeline.