Inertia & Decay
Relevant source files
The following files were used as context for generating this wiki page:
The Inertia & Decay system provides a set of pre-configured transition profiles designed to simulate physical momentum in user interface interactions. Primarily used for scrolling and dragging gestures, these transitions calculate movement based on an initial velocity and gradually decelerate (decay) until the movement stops.
This module is a core part of the @pcstyle/motion library's transition suite, working alongside Spring Transitions and Tween Transitions to provide a comprehensive physics-based animation toolkit.
Sources: src/transitions/inertia.ts, src/transitions/index.ts:3, src/index.ts:11
Core Architecture
The system is built upon the inertia transition type from Framer Motion. It defines specific presets that control how velocity is reduced over time through parameters like power, timeConstant, and bounceStiffness.
Inertia Transition Logic
When an inertia animation is triggered (typically after a user releases a drag or scroll gesture), the system follows a decay curve. If the animation hits a defined boundary, it can transition into a "bounce" state using spring physics.
The diagram above illustrates the decision flow when an inertia-based transition is initiated following a user gesture.
Sources: src/transitions/inertia.ts:34-39, src/gestures/drag.ts:6-10
Transition Presets
The library exports several inertia configurations tailored for different interaction speeds and physical "feels."
Standard Profiles
These profiles control the rate of deceleration without boundary bouncing logic.
| Preset | Velocity | Power | Time Constant | Description |
|---|---|---|---|---|
inertiaScroll | 50 | 0.8 | 700 | Standard deceleration for scrollable containers. |
inertiaQuick | 50 | 0.4 | 300 | Rapid decay for quick stops. |
inertiaGlide | 50 | 0.9 | 1000 | Long, smooth deceleration for a "gliding" feel. |
Sources: src/transitions/inertia.ts:8-32
Bouncy Inertia
The inertiaBounce preset is specifically designed for scenarios where an element should rebound when reaching the end of its permitted range.
- Velocity: 50
- Bounce Stiffness: 300
- Bounce Damping: 10
Sources: src/transitions/inertia.ts:34-39
Integration with Gestures
Inertia transitions are most frequently utilized in conjunction with drag gestures. The drag module provides configurations that enable momentum-based movements.
Drag Momentum Configuration
The library defines configurations where dragMomentum is enabled by default for specific drag types:
dragFree: Allows free movement in all directions with momentum and an elastic factor of 0.2.dragX/dragY: Axis-locked dragging that retains inertia decay upon release.dragSlider: Optimized for slider components, utilizing a specificdragTransitionwithbounceStiffness: 300andbounceDamping: 20to control the end-of-drag inertia.
Sources: src/gestures/drag.ts:8-44
Transition Relationship
This class diagram shows the relationship between base transitions, inertia-specific properties, and their application within drag configurations.
Sources: src/transitions/inertia.ts:1-6, src/gestures/drag.ts:39-44
Implementation Example
The presets are defined as constant objects that satisfy the Transition type from Framer Motion, allowing them to be spread into component props or animation definitions.
// src/transitions/inertia.ts:8-13
export const inertiaScroll: Transition = {
type: "inertia",
velocity: 50,
power: 0.8,
timeConstant: 700,
};
Sources: src/transitions/inertia.ts:8-13
Summary
The Inertia & Decay system enables realistic, physics-based movement for interactive elements in the @pcstyle/motion ecosystem. By providing pre-tuned constants for scrolling, gliding, and bouncing, it ensures consistent "tactile" feedback across different components while abstracting the complexity of velocity-based decay calculations.