Spring Physics

Relevant source files

The following files were used as context for generating this wiki page:

• src/transitions/spring.ts
• src/variants/scale.ts
• src/transitions/inertia.ts
• src/gestures/drag.ts
• src/transitions/index.ts

Spring Physics in the @pcstyle/motion library provides a set of physics-based transition presets designed to create natural, fluid, and responsive animations. By leveraging Framer Motion's spring solver, the library abstracts complex physics parameters into reusable constants categorized by their physical behavior, such as stiffness, damping, and mass.

These transitions are primarily used to define how properties like scale, position, and opacity change over time, moving away from fixed durations toward dynamic movement that reacts to user interaction.

Transition Presets

The library exports several pre-configured Transition objects that define specific physical behaviors. These presets allow developers to maintain consistency across the UI without manually recalculating physics constants.

Core Spring Constants

The system relies on three primary variables to control the "feel" of the animation:

• Stiffness: Controls the "snap" or speed of the initial movement.
• Damping: Controls the friction that slows the spring down, preventing or encouraging oscillation.
• Mass: Controls the perceived weight of the object, affecting momentum.

Preset	Stiffness	Damping	Mass / Bounce	Description
springSnappy	400	30	-	Quick, responsive spring for UI interactions.
springBouncy	300	10	-	Playful spring with high oscillation.
springSmooth	-	-	0.25 (Bounce)	Duration-based (0.5s) smooth spring.
springGentle	100	20	-	Subtle, slow-moving animations.
springStiff	500	25	-	High-frequency responsive feedback.
springWobbly	200	5	-	Low damping for attention-grabbing effects.
springDrag	300	30	0.8 (Mass)	Optimized for following draggable elements.

Sources: src/transitions/spring.ts:9-52

Implementation in Variants

Spring physics are integrated directly into animation variants to define entry and exit behaviors. This is particularly evident in scaling and "pop" animations where physical momentum enhances the visual feedback.

Pop and Bounce Variants

The library uses high-stiffness springs to create "pop-in" effects, where an element expands rapidly and settles with slight oscillation.

export const popIn: Variants = {
  hidden: { opacity: 0, scale: 0.5 },
  visible: { 
    opacity: 1, 
    scale: 1,
    transition: { type: "spring", stiffness: 400, damping: 15 }
  },
};

Sources: src/variants/scale.ts:16-23

The following diagram illustrates how a variant utilizes a spring transition during a state change:

The diagram shows the logic flow from a hidden state to a visible state using physics parameters. Sources: src/variants/scale.ts:32-39, src/transitions/spring.ts:16-20

Interaction Physics

Physics-based movement is heavily utilized in gesture-based interactions, specifically for dragging and boundary behaviors.

Drag and Elasticity

When an element is dragged, the library applies dragElastic and dragTransition to simulate physical resistance and snapping.

• Elasticity: Defines the degree of pull when a user drags beyond the defined constraints.
• Momentum: Uses spring-like deceleration (inertia) when the user releases the element.

Configuration	Property	Value	Source
dragFree	dragElastic	0.2	src/gestures/drag.ts:10
dragConstrained	dragElastic	0.1	src/gestures/drag.ts:33
dragSlider	bounceStiffness	300	src/gestures/drag.ts:48
dragSlider	bounceDamping	20	src/gestures/drag.ts:48

Inertia and Deceleration

While technically a separate transition type, inertia transitions in the library simulate spring-like "bouncy bounds" when an object reaches a limit.

This sequence shows the interaction between user release and physics-based boundary snapping. Sources: src/transitions/inertia.ts:31-36, src/gestures/drag.ts:48

Summary

The Spring Physics module centralizes the mathematical constants required for natural motion. By categorizing these into named exports like springSnappy or springWobbly, the project ensures that UI elements react with consistent physical weight and responsiveness across different modules like variants and gestures.

Sources: src/transitions/index.ts:1-3, src/transitions/spring.ts:1-53