1
# Motion and Animation
2

3
Physics-based animations and smooth transitions between state values with spring and tween effects.
4

5
## Capabilities
6

7
### Spring Animation
8

9
Create stores with spring-based physics animations that simulate natural motion with bounce and elasticity.
10

11
```javascript { .api }
12
/**
13
 * Creates a store whose value is animated with spring physics
14
 * @param value - Initial value
15
 * @param opts - Spring configuration options
16
 * @returns Spring store with physics-based animation
17
 */
18
function spring<T = any>(value?: T, opts?: SpringOpts): Spring<T>;
19

20
interface Spring<T> extends Readable<T> {
21
  /** Set new target value with optional animation options */
22
  set: (new_value: T, opts?: SpringUpdateOpts) => Promise<void>;
23
  /** Update value using callback with optional animation options */
24
  update: (fn: Updater<T>, opts?: SpringUpdateOpts) => Promise<void>;
25
  /** Spring stiffness (0-1, higher = more responsive) */
26
  stiffness: number;
27
  /** Spring damping (0-1, higher = less oscillation) */
28
  damping: number;
29
  /** Animation precision threshold */
30
  precision: number;
31
}
32

33
interface SpringOpts {
34
  /** Stiffness controls responsiveness (default: 0.15) */
35
  stiffness?: number;
36
  /** Damping controls oscillation (default: 0.8) */
37
  damping?: number;
38
  /** Precision threshold for stopping animation (default: 0.01) */
39
  precision?: number;
40
}
41

42
interface SpringUpdateOpts {
43
  /** Hard transition - skip animation */
44
  hard?: boolean;
45
  /** Soft transition - gradual mass recovery */
46
  soft?: string | number | boolean;
47
}
48

49
type Updater<T> = (target_value: T, value: T) => T;
50
```
51

52
**Usage Examples:**
53

54
```javascript
55
import { spring } from "svelte/motion";
56

57
// Basic spring store
58
const coords = spring({ x: 50, y: 50 }, {
59
  stiffness: 0.1,
60
  damping: 0.25
61
});
62

63
// Animate to new position
64
coords.set({ x: 100, y: 200 });
65

66
// Update with callback
67
coords.update((target, current) => ({
68
  x: target.x + 10,
69
  y: target.y + 10
70
}));
71

72
// Responsive spring for UI elements
73
const scale = spring(1, {
74
  stiffness: 0.3,
75
  damping: 0.6
76
});
77

78
// Mouse hover effects
79
function handleMouseEnter() {
80
  scale.set(1.1);
81
}
82

83
function handleMouseLeave() {
84
  scale.set(1);
85
}
86

87
// Hard vs soft transitions
88
const position = spring({ x: 0, y: 0 });
89

90
// Hard transition (no animation)
91
position.set({ x: 100, y: 100 }, { hard: true });
92

93
// Soft transition (gradual acceleration)
94
position.set({ x: 200, y: 200 }, { soft: true });
95
```
96

97
### Tween Animation
98

99
Create stores with smooth, time-based transitions between values using easing functions.
100

101
```javascript { .api }
102
/**
103
 * Creates a store that provides smooth transitions between state values over time
104
 * @param value - Initial value
105
 * @param defaults - Default tween options
106
 * @returns Tweened store with time-based animation
107
 */
108
function tweened<T>(value?: T, defaults?: TweenedOptions<T>): Tweened<T>;
109

110
interface Tweened<T> extends Readable<T> {
111
  /** Set new value with optional tween options */
112
  set(value: T, opts?: TweenedOptions<T>): Promise<void>;
113
  /** Update value using callback with optional tween options */
114
  update(updater: Updater<T>, opts?: TweenedOptions<T>): Promise<void>;
115
}
116

117
interface TweenedOptions<T> {
118
  /** Delay before animation starts (ms) */
119
  delay?: number;
120
  /** Animation duration (ms) or function */
121
  duration?: number | ((from: T, to: T) => number);
122
  /** Easing function */
123
  easing?: (t: number) => number;
124
  /** Custom interpolation function */
125
  interpolate?: (a: T, b: T) => (t: number) => T;
126
}
127

128
type Updater<T> = (value: T) => T;
129
```
130

131
**Usage Examples:**
132

133
```javascript
134
import { tweened } from "svelte/motion";
135
import { cubicOut } from "svelte/easing";
136

137
// Basic tweened store
138
const progress = tweened(0, {
139
  duration: 400,
140
  easing: cubicOut
141
});
142

143
// Animate progress bar
144
progress.set(75);
145

146
// Dynamic duration based on distance
147
const position = tweened(0, {
148
  duration: (from, to) => Math.abs(to - from) * 10,
149
  easing: cubicOut
150
});
151

152
// Color transitions
153
const color = tweened([255, 0, 0], {
154
  duration: 800,
155
  interpolate: (from, to) => (t) => [
156
    Math.round(from[0] + (to[0] - from[0]) * t),
157
    Math.round(from[1] + (to[1] - from[1]) * t),
158
    Math.round(from[2] + (to[2] - from[2]) * t)
159
  ]
160
});
161

162
color.set([0, 255, 0]); // Animate from red to green
163

164
// Text size animation
165
const fontSize = tweened(16, {
166
  duration: 300,
167
  easing: cubicOut
168
});
169

170
// Smooth number counting
171
const counter = tweened(0, { duration: 2000 });
172
counter.set(1000); // Count up to 1000 over 2 seconds
173

174
// Promise-based animation chaining
175
async function animateSequence() {
176
  await progress.set(25);
177
  await progress.set(50);
178
  await progress.set(100);
179
  console.log('Animation sequence complete');
180
}
181
```
182

183
### Custom Interpolation
184

185
Advanced usage with custom interpolation functions for complex data types.
186

187
**Object Interpolation:**
188

189
```javascript
190
import { tweened } from "svelte/motion";
191

192
const objectStore = tweened({ x: 0, y: 0, opacity: 1 }, {
193
  interpolate: (from, to) => (t) => ({
194
    x: from.x + (to.x - from.x) * t,
195
    y: from.y + (to.y - from.y) * t,
196
    opacity: from.opacity + (to.opacity - from.opacity) * t
197
  })
198
});
199

200
objectStore.set({ x: 100, y: 200, opacity: 0.5 });
201
```
202

203
**Date Interpolation:**
204

205
```javascript
206
import { tweened } from "svelte/motion";
207

208
const dateStore = tweened(new Date(), {
209
  interpolate: (from, to) => (t) => {
210
    const fromTime = from.getTime();
211
    const toTime = to.getTime();
212
    return new Date(fromTime + (toTime - fromTime) * t);
213
  }
214
});
215

216
dateStore.set(new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)); // Week from now
217
```
218

219
### Animation Patterns
220

221
Common patterns for using motion stores in Svelte applications.
222

223
**Coordinated Animations:**
224

225
```javascript
226
import { spring } from "svelte/motion";
227

228
const mainPosition = spring({ x: 0, y: 0 });
229
const shadowPosition = spring({ x: 0, y: 0 }, {
230
  stiffness: 0.05,
231
  damping: 0.9
232
});
233

234
// Main element moves immediately, shadow follows with delay
235
function moveTo(x, y) {
236
  mainPosition.set({ x, y });
237
  setTimeout(() => shadowPosition.set({ x, y }), 100);
238
}
239
```
240

241
**Gesture-based Animation:**
242

243
```javascript
244
import { spring } from "svelte/motion";
245

246
const dragPosition = spring({ x: 0, y: 0 }, {
247
  stiffness: 0.2,
248
  damping: 0.4
249
});
250

251
let isDragging = false;
252

253
function handleMouseDown() {
254
  isDragging = true;
255
  // Stiffer spring while dragging
256
  dragPosition.stiffness = 1;
257
  dragPosition.damping = 1;
258
}
259

260
function handleMouseUp() {
261
  isDragging = false;
262
  // Bouncy spring when released
263
  dragPosition.stiffness = 0.1;
264
  dragPosition.damping = 0.3;
265
  // Snap back to origin
266
  dragPosition.set({ x: 0, y: 0 });
267
}
268
```
269

270
**Loading Animations:**
271

272
```javascript
273
import { tweened } from "svelte/motion";
274
import { linear } from "svelte/easing";
275

276
const loadingProgress = tweened(0, {
277
  duration: 3000,
278
  easing: linear
279
});
280

281
async function simulateLoading() {
282
  await loadingProgress.set(30);  // Quick initial progress
283
  await loadingProgress.set(60);  // Slower middle phase
284
  await loadingProgress.set(100); // Final completion
285
}
286
```
287

288
## Integration with Components
289

290
Using motion stores effectively in Svelte components:
291

292
```javascript
293
// In a Svelte component
294
import { spring, tweened } from "svelte/motion";
295
import { cubicOut } from "svelte/easing";
296

297
const scale = spring(1);
298
const opacity = tweened(1);
299

300
function handleHover() {
301
  scale.set(1.1);
302
  opacity.set(0.8);
303
}
304

305
function handleLeave() {
306
  scale.set(1);
307
  opacity.set(1);
308
}
309
```
310

311
```html
312
<!-- Template using reactive values -->
313
<div 
314
  style="transform: scale({$scale}); opacity: {$opacity}"
315
  on:mouseenter={handleHover}
316
  on:mouseleave={handleLeave}
317
>
318
  Animated element
319
</div>
320
```