0
# Animation Actions
1

2
Animation actions provide control and introspection capabilities for managing running animations, getting/setting properties, and controlling animation flow.
3

4
## Control Actions
5

6
### Stop Action
7

8
```typescript { .api }
9
function Velocity(elements: VelocityElements, action: "stop"): VelocityResult;
10
function Velocity(elements: VelocityElements, action: "stop", queue: string): VelocityResult;
11
function Velocity(elements: VelocityElements, action: "stop", clearQueue: true): VelocityResult;
12
function Velocity(elements: VelocityElements, action: "stop", queue: string | false, stopAll: true): VelocityResult;
13
function Velocity(action: "stop", queue?: string | false, stopAll?: true): VelocityResult;
14
```
15

16
Stops running animations on elements (or globally if no elements specified). Optionally specify a queue name to stop only animations in that queue, or pass `true` for stopAll to clear all queued animations.
17

18
### Pause Action
19

20
```typescript { .api }
21
function Velocity(elements: VelocityElements, action: "pause"): VelocityResult;
22
function Velocity(elements: VelocityElements, action: "pause", queue: string): VelocityResult;
23
function Velocity(action: "pause", queue?: string): VelocityResult;
24
```
25

26
Pauses all running animations on the specified elements (or globally if no elements specified). Animations can be resumed later. Optionally specify a queue name to pause only animations in that queue.
27

28
### Resume Action
29

30
```typescript { .api }
31
function Velocity(elements: VelocityElements, action: "resume"): VelocityResult;
32
function Velocity(elements: VelocityElements, action: "resume", queue: string): VelocityResult;
33
function Velocity(action: "resume", queue?: string): VelocityResult;
34
```
35

36
Resumes previously paused animations on the specified elements (or globally if no elements specified). Optionally specify a queue name to resume only animations in that queue.
37

38
### Finish Action
39

40
```typescript { .api }
41
function Velocity(elements: VelocityElements, action: "finish"): VelocityResult;
42
function Velocity(elements: VelocityElements, action: "finish", queue: string): VelocityResult;
43
```
44

45
Immediately completes running animations, jumping to their end states. Optionally specify a queue name.
46

47
### Reverse Action
48

49
```typescript { .api }
50
function Velocity(elements: VelocityElements, action: "reverse"): VelocityResult;
51
```
52

53
Reverses the direction of running animations. If no animations are running, reverses the most recent animation.
54

55
## Property Actions
56

57
### Style Action
58

59
```typescript { .api }
60
function Velocity(elements: VelocityElements, action: "style", property: string): string;
61
function Velocity(
62
  elements: VelocityElements, 
63
  action: "style", 
64
  properties: {[property: string]: VelocityPropertyValue}
65
): VelocityResult;
66
```
67

68
Gets or sets CSS style properties. When getting, returns the computed style value. When setting, applies the properties immediately.
69

70
### Property Action
71

72
```typescript { .api }
73
function Velocity(elements: VelocityElements, action: "property", property: string): any;
74
function Velocity(
75
  elements: VelocityElements,
76
  action: "property", 
77
  properties: {[property: string]: any}
78
): VelocityResult;
79
```
80

81
Gets or sets element properties (not CSS styles). Useful for accessing DOM properties like `scrollTop`, `scrollLeft`, etc.
82

83
## Utility Actions
84

85
### Option Action
86

87
```typescript { .api }
88
function Velocity(elements: VelocityElements, action: "option", option: string): any;
89
function Velocity(
90
  elements: VelocityElements,
91
  action: "option",
92
  options: {[option: string]: any}
93
): VelocityResult;
94
```
95

96
Gets or sets animation options on running animations. Available options include all VelocityOptions properties.
97

98
### Tween Action
99

100
```typescript { .api }
101
function Velocity(
102
  elements: VelocityElements,
103
  action: "tween",
104
  properties: Properties<any>,
105
  progress: number
106
): VelocityResult;
107
```
108

109
Calculates intermediate property values at a specific progress point (0-1) without creating an animation.
110

111
## Registration Actions
112

113
### Register Easing Action
114

115
```typescript { .api }
116
function Velocity(action: "registerEasing", name: string, easing: VelocityEasingFn): void;
117
```
118

119
Registers a custom easing function for use throughout the application.
120

121
### Register Normalization Action
122

123
```typescript { .api }
124
function Velocity(
125
  action: "registerNormalization",
126
  constructor: {new: () => Element} | string,
127
  name: string,
128
  normalization: VelocityNormalizationsFn,
129
  unit?: string,
130
  cache?: boolean
131
): void;
132

133
function Velocity(
134
  action: "registerNormalization",
135
  constructor: {new: () => Element} | string,
136
  name: string,
137
  normalization: VelocityNormalizationsFn,
138
  cache?: boolean
139
): void;
140
```
141

142
Registers a custom normalization handler for CSS properties. This is the interface between Velocity and the actual properties.
143

144
### Register Sequence Action
145

146
```typescript { .api }
147
function Velocity(action: "registerSequence", name: string, sequence: VelocitySequence): void;
148
function Velocity(action: "registerSequence", sequences: {[name: string]: VelocitySequence}): void;
149
```
150

151
Registers custom animation sequences for use throughout the application.
152

153
### Has Normalization Action
154

155
```typescript { .api }
156
function Velocity(
157
  action: "hasNormalization",
158
  constructor: {new: () => Element} | string,
159
  name: string
160
): boolean;
161
```
162

163
Checks if there is a normalization handler for the named type of Element and property.
164

165
## Usage Examples
166

167
### Animation Control
168

169
```typescript
170
import Velocity from "velocity-animate";
171

172
const element = document.getElementById("myElement");
173

174
// Start an animation
175
Velocity(element, { translateX: "200px" }, { duration: 2000 });
176

177
// Stop the animation
178
Velocity(element, "stop");
179

180
// Start another animation
181
Velocity(element, { rotateZ: "360deg" }, { duration: 3000 });
182

183
// Pause it
184
Velocity(element, "pause");
185

186
// Resume it later
187
setTimeout(() => {
188
  Velocity(element, "resume");
189
}, 1000);
190

191
// Or finish it immediately
192
Velocity(element, "finish");
193
```
194

195
### Queue Management
196

197
```typescript
198
// Queue multiple animations
199
Velocity(element, { translateX: "100px" }, { queue: "slideQueue" });
200
Velocity(element, { translateY: "100px" }, { queue: "slideQueue" });
201
Velocity(element, { rotateZ: "90deg" }, { queue: "rotateQueue" });
202

203
// Stop only animations in slideQueue
204
Velocity(element, "stop", "slideQueue");
205

206
// Stop all animations and clear all queues
207
Velocity(element, "stop", true);
208
```
209

210
### Reverse Animation
211

212
```typescript
213
// Start animation
214
Velocity(element, { 
215
  translateX: "300px",
216
  rotateZ: "180deg",
217
  scale: 1.5
218
}, 1500);
219

220
// Reverse it mid-animation
221
setTimeout(() => {
222
  Velocity(element, "reverse");
223
}, 750);
224
```
225

226
### Property Getting/Setting
227

228
```typescript
229
// Get computed CSS style
230
const opacity = Velocity(element, "style", "opacity");
231
const transform = Velocity(element, "style", "transform");
232

233
// Set CSS styles immediately
234
Velocity(element, "style", {
235
  opacity: 0.5,
236
  backgroundColor: "#ff0000",
237
  display: "block"
238
});
239

240
// Get DOM properties
241
const scrollTop = Velocity(element, "property", "scrollTop");
242
const offsetWidth = Velocity(element, "property", "offsetWidth");
243

244
// Set DOM properties
245
Velocity(element, "property", {
246
  scrollTop: 100,
247
  textContent: "New content"
248
});
249
```
250

251
### Option Inspection
252

253
```typescript
254
// Start animation with options
255
Velocity(element, { translateX: "200px" }, {
256
  duration: 2000,
257
  easing: "easeInOutQuad",
258
  loop: 3
259
});
260

261
// Get current options
262
const duration = Velocity(element, "option", "duration");
263
const easing = Velocity(element, "option", "easing");
264
const loop = Velocity(element, "option", "loop");
265

266
// Modify options on running animation
267
Velocity(element, "option", {
268
  duration: 3000,  // Extend the animation
269
  loop: 5         // Increase loop count
270
});
271
```
272

273
### Tween Calculation
274

275
```typescript
276
// Calculate intermediate values without animating
277
Velocity(element, "tween", {
278
  translateX: "200px",
279
  opacity: 0.5,
280
  scale: 1.2
281
}, 0.5); // 50% progress
282

283
// Useful for custom animation loops or progress bars
284
for (let i = 0; i <= 100; i += 10) {
285
  const progress = i / 100;
286
  Velocity(element, "tween", {
287
    rotateZ: "360deg",
288
    scale: [1, 2]
289
  }, progress);
290
  
291
  // element now has properties set to the calculated intermediate values
292
  console.log(`Progress: ${i}%, Rotation: ${element.style.transform}`);
293
}
294
```
295

296
### Multiple Elements
297

298
```typescript
299
const elements = document.querySelectorAll(".animated");
300

301
// Control all elements at once
302
Velocity(elements, { translateY: "50px" }, 1000);
303

304
// Pause all
305
Velocity(elements, "pause");
306

307
// Resume all
308
Velocity(elements, "resume");
309

310
// Stop all and clear queues
311
Velocity(elements, "stop", true);
312

313
// Set styles on all elements
314
Velocity(elements, "style", { opacity: 0.8 });
315
```
316

317
### Registration Actions
318

319
```typescript
320
// Register a custom easing function
321
Velocity("registerEasing", "myCustomEasing", function(t, b, c, d) {
322
  // t = current time, b = start value, c = change, d = duration
323
  return c * t / d + b; // Linear easing
324
});
325

326
// Use the registered easing
327
Velocity(element, { translateX: "200px" }, {
328
  duration: 1000,
329
  easing: "myCustomEasing"
330
});
331

332
// Register a custom animation sequence
333
Velocity("registerSequence", "customBounce", {
334
  duration: 1000,
335
  "0%": { transform: "translateY(0px)" },
336
  "50%": { transform: "translateY(-30px)" },
337
  "100%": { transform: "translateY(0px)" }
338
});
339

340
// Register multiple sequences at once
341
Velocity("registerSequence", {
342
  "wiggle": {
343
    duration: 500,
344
    "0%": { transform: "rotate(0deg)" },
345
    "25%": { transform: "rotate(5deg)" },
346
    "75%": { transform: "rotate(-5deg)" },
347
    "100%": { transform: "rotate(0deg)" }
348
  },
349
  "shake": {
350
    duration: 600,
351
    "0%": { transform: "translateX(0px)" },
352
    "25%": { transform: "translateX(-10px)" },
353
    "75%": { transform: "translateX(10px)" },
354
    "100%": { transform: "translateX(0px)" }
355
  }
356
});
357

358
// Use registered sequences
359
Velocity(element, "customBounce");
360
Velocity(element, "wiggle");
361

362
// Check if normalization exists
363
const hasOpacity = Velocity("hasNormalization", "HTMLElement", "opacity");
364
if (hasOpacity) {
365
  console.log("Opacity normalization is available");
366
}
367
```