1
# Motion & Animation
2

3
Svelte provides powerful animation utilities including springs, tweens, and FLIP animations for creating smooth, physics-based motion effects.
4

5
## Capabilities
6

7
### Spring
8

9
A reactive spring animation class that moves values towards targets with physics-based motion.
10

11
```typescript { .api }
12
/**
13
 * A wrapper for a value that behaves in a spring-like fashion
14
 */
15
class Spring<T> {
16
  constructor(value: T, options?: SpringOpts);
17
  
18
  /** Create a spring whose value is bound to the return value of fn */
19
  static of<U>(fn: () => U, options?: SpringOpts): Spring<U>;
20
  
21
  /** Sets target value and returns promise that resolves when spring settles */
22
  set(value: T, options?: SpringUpdateOpts): Promise<void>;
23
  
24
  /** Current value of the spring */
25
  get current(): T;
26
  
27
  /** Target value the spring is moving towards */
28
  target: T;
29
  
30
  /** Spring stiffness (0-1, higher = more responsive) */
31
  stiffness: number;
32
  
33
  /** Spring damping (0-1, higher = less oscillation) */
34
  damping: number;
35
  
36
  /** Precision threshold for settling */
37
  precision: number;
38
}
39
```
40

41
**Usage Examples:**
42

43
```typescript
44
import { Spring } from "svelte/motion";
45

46
// Basic spring
47
const spring = new Spring(0);
48

49
// Spring with options
50
const spring = new Spring(0, {
51
  stiffness: 0.1,
52
  damping: 0.25,
53
  precision: 0.01
54
});
55

56
// Use in reactive context
57
let targetValue = $state(0);
58
const animatedValue = Spring.of(() => targetValue);
59

60
// Set target values
61
spring.target = 100; // Sets target immediately
62
await spring.set(100); // Returns promise when settled
63

64
// Set with options
65
await spring.set(100, {
66
  instant: true, // Jump immediately
67
  preserveMomentum: 500 // Continue current trajectory for 500ms
68
});
69

70
// Access current value
71
console.log(spring.current); // Current animated value
72
```
73

74
### Tween
75

76
A reactive tween animation class that smoothly interpolates between values over time.
77

78
```typescript { .api }
79
/**
80
 * A wrapper for a value that tweens smoothly to its target value
81
 */
82
class Tween<T> {
83
  constructor(value: T, options?: TweenedOptions<T>);
84
  
85
  /** Create a tween whose value is bound to the return value of fn */
86
  static of<U>(fn: () => U, options?: TweenedOptions<U>): Tween<U>;
87
  
88
  /** Sets target value and returns promise when tween completes */
89
  set(value: T, options?: TweenedOptions<T>): Promise<void>;
90
  
91
  /** Current value of the tween */
92
  get current(): T;
93
  
94
  /** Target value the tween is moving towards */
95
  get target(): T;
96
  set target(value: T);
97
}
98
```
99

100
**Usage Examples:**
101

102
```typescript
103
import { Tween } from "svelte/motion";
104
import { cubicOut } from "svelte/easing";
105

106
// Basic tween
107
const tween = new Tween(0);
108

109
// Tween with options
110
const tween = new Tween(0, {
111
  duration: 400,
112
  easing: cubicOut,
113
  delay: 100
114
});
115

116
// Use in reactive context
117
let targetValue = $state(0);
118
const animatedValue = Tween.of(() => targetValue);
119

120
// Set target values
121
await tween.set(100); // Uses default options
122

123
// Set with custom options
124
await tween.set(100, {
125
  duration: 1000,
126
  easing: t => t * t, // Custom easing
127
  delay: 200
128
});
129

130
// Custom interpolation for complex values
131
const colorTween = new Tween({ r: 255, g: 0, b: 0 }, {
132
  interpolate: (from, to) => t => ({
133
    r: Math.round(from.r + (to.r - from.r) * t),
134
    g: Math.round(from.g + (to.g - from.g) * t),
135
    b: Math.round(from.b + (to.b - from.b) * t)
136
  })
137
});
138
```
139

140
### FLIP Animation
141

142
The `flip` function calculates start and end positions of elements and animates between them using the FLIP technique.
143

144
```typescript { .api }
145
/**
146
 * FLIP animation for element position changes
147
 * @param node - Element to animate
148
 * @param params - From/to rectangles and animation options
149
 * @returns Animation configuration
150
 */
151
function flip(
152
  node: Element,
153
  { from, to }: { from: DOMRect; to: DOMRect },
154
  params?: FlipParams
155
): AnimationConfig;
156
```
157

158
**Usage Examples:**
159

160
```typescript
161
import { flip } from "svelte/animate";
162

163
// In a Svelte component with keyed each block
164
let items = $state([
165
  { id: 1, name: "Item 1" },
166
  { id: 2, name: "Item 2" },
167
  { id: 3, name: "Item 3" }
168
]);
169

170
function shuffle() {
171
  items = items.sort(() => Math.random() - 0.5);
172
}
173

174
// Template usage with animate directive
175
/*
176
{#each items as item (item.id)}
177
  <div animate:flip={{ duration: 300 }}>
178
    {item.name}
179
  </div>
180
{/each}
181
*/
182

183
// Programmatic usage
184
function animateMove(element, fromRect, toRect) {
185
  const animation = flip(element, 
186
    { from: fromRect, to: toRect },
187
    { duration: 400, easing: cubicOut }
188
  );
189
  
190
  // Apply animation manually
191
  element.style.animation = animation.css(0, 1);
192
}
193
```
194

195
### Legacy Motion Stores
196

197
Legacy store-based motion utilities for Svelte 4 compatibility.
198

199
```typescript { .api }
200
/**
201
 * @deprecated Use Spring class instead
202
 * Creates a spring store with reactive value
203
 */
204
function spring<T = any>(value?: T, opts?: SpringOpts): Spring<T>;
205

206
/**
207
 * @deprecated Use Tween class instead  
208
 * Creates a tweened store with reactive value
209
 */
210
function tweened<T>(value?: T, defaults?: TweenedOptions<T>): Tweened<T>;
211
```
212

213
**Usage Examples:**
214

215
```typescript
216
import { spring, tweened } from "svelte/motion";
217

218
// Legacy spring store
219
const springStore = spring(0, {
220
  stiffness: 0.1,
221
  damping: 0.25
222
});
223

224
springStore.set(100);
225

226
// Legacy tweened store
227
const tweenedStore = tweened(0, {
228
  duration: 400,
229
  easing: t => t * t
230
});
231

232
tweenedStore.set(100);
233

234
// Subscribe to changes
235
springStore.subscribe(value => {
236
  console.log("Spring value:", value);
237
});
238
```
239

240
### Motion Utilities
241

242
Additional utilities for motion and accessibility.
243

244
```typescript { .api }
245
/**
246
 * MediaQuery for reduced motion preference
247
 */
248
const prefersReducedMotion: MediaQuery;
249
```
250

251
**Usage Examples:**
252

253
```typescript
254
import { prefersReducedMotion } from "svelte/motion";
255

256
// Check user's motion preference
257
const shouldAnimate = !prefersReducedMotion.current;
258

259
// Use in animation decisions
260
const duration = prefersReducedMotion.current ? 0 : 400;
261

262
// Reactive usage
263
$effect(() => {
264
  if (prefersReducedMotion.current) {
265
    // Disable animations
266
    spring.set(targetValue, { instant: true });
267
  } else {
268
    // Enable animations
269
    spring.set(targetValue);
270
  }
271
});
272
```
273

274
## Types
275

276
```typescript { .api }
277
interface SpringOpts {
278
  stiffness?: number;
279
  damping?: number;
280
  precision?: number;
281
}
282

283
interface SpringUpdateOpts {
284
  instant?: boolean;
285
  preserveMomentum?: number;
286
}
287

288
interface TweenedOptions<T> {
289
  delay?: number;
290
  duration?: number | ((from: T, to: T) => number);
291
  easing?: (t: number) => number;
292
  interpolate?: (a: T, b: T) => (t: number) => T;
293
}
294

295
interface FlipParams {
296
  delay?: number;
297
  duration?: number | ((len: number) => number);
298
  easing?: (t: number) => number;
299
}
300

301
interface AnimationConfig {
302
  delay?: number;
303
  duration?: number;
304
  easing?: (t: number) => number;
305
  css?: (t: number, u: number) => string;
306
  tick?: (t: number, u: number) => void;
307
}
308

309
interface MediaQuery {
310
  current: boolean;
311
}
312
```
313

314
## Best Practices
315

316
1. **Use Spring for interactive elements**: Springs feel more natural for user-driven animations
317
2. **Use Tween for choreographed sequences**: Tweens provide precise timing control
318
3. **Respect user preferences**: Always check `prefersReducedMotion` for accessibility
319
4. **Clean up animations**: Use cleanup functions in effects to cancel ongoing animations
320
5. **Performance considerations**: Prefer `transform` and `opacity` properties for smooth animations