0
# Configuration & Utilities
1

2
Velocity provides global configuration options, state management, debugging tools, and utility functions for extending and customizing its capabilities.
3

4
## Static Properties
5

6
```typescript { .api }
7
interface VelocityStatic {
8
  version: string;
9
  defaults: StrictVelocityOptions & { reset?: () => void };
10
  State: VelocityState;
11
  Actions: { [name: string]: VelocityActionFn };
12
  Easings: { [name: string]: VelocityEasingFn };
13
  Sequences: { [name: string]: SequenceList };
14
  patch: (target: any, addGlobal?: boolean) => void;
15
  debug: boolean | 1 | 2;
16
  mock: boolean;
17
}
18
```
19

20
## Version Information
21

22
```typescript { .api }
23
const version: string;
24
```
25

26
The current version of Velocity as a string (e.g., "2.0.6").
27

28
## Default Options
29

30
```typescript { .api }
31
interface VelocityDefaults extends StrictVelocityOptions {
32
  reset?: () => void;
33
}
34

35
const defaults: VelocityDefaults;
36
```
37

38
Global default options applied to all animations. Can be modified to change behavior across the entire application.
39

40
### Default Values
41

42
```typescript { .api }
43
const defaultOptions = {
44
  duration: 400,           // milliseconds
45
  easing: "swing",         // default easing function
46
  queue: "",               // default queue name
47
  begin: undefined,        // begin callback
48
  progress: undefined,     // progress callback  
49
  complete: undefined,     // complete callback
50
  display: undefined,      // CSS display value
51
  visibility: undefined,   // CSS visibility value
52
  loop: false,            // loop count or boolean
53
  delay: 0,               // delay before animation starts
54
  mobileHA: true,         // mobile hardware acceleration
55
  // ... other options
56
};
57
```
58

59
## State Management
60

61
```typescript { .api }
62
interface VelocityState {
63
  isClient: boolean;
64
  isMobile: boolean;
65
  isGingerbread: boolean;
66
  isChrome: boolean;
67
  isFirefox: boolean;
68
  prefixElement: HTMLElement;
69
  prefixMatches: { [property: string]: string };
70
  calls: AnimationCall[];
71
  first?: AnimationCall;
72
  last?: AnimationCall;
73
  firstNew?: AnimationCall;
74
  readonly windowScrollAnchor: boolean;
75
  readonly scrollAnchor: Window | HTMLElement | Node | boolean;
76
  readonly scrollPropertyLeft: string;
77
  readonly scrollPropertyTop: string;
78
  readonly className: string;
79
  isTicking: boolean;
80
}
81

82
const State: VelocityState;
83
```
84

85
### State Properties
86

87
#### Environment Detection
88
- **isClient**: True if running in a browser environment
89
- **isMobile**: True if running on a mobile device
90
- **isGingerbread**: True if running on Android 2.3 (Gingerbread)
91
- **isChrome**: True if running in Chrome browser
92
- **isFirefox**: True if running in Firefox browser
93

94
#### CSS Prefix Management
95
- **prefixElement**: Element used for CSS prefix detection
96
- **prefixMatches**: Map of CSS properties to their prefixed versions
97
- **className**: CSS class name used for styling
98

99
#### Animation Queue Management
100
- **calls**: Array of all active animation calls
101
- **first**: First animation call in the queue (optional)
102
- **last**: Last animation call in the queue (optional)
103
- **firstNew**: First new animation call to be processed (optional)
104
- **isTicking**: Whether the animation ticker is currently running
105

106
#### Scroll Management
107
- **windowScrollAnchor**: Whether to use window as scroll anchor
108
- **scrollAnchor**: Element or window to use as scroll reference
109
- **scrollPropertyLeft**: CSS property name for horizontal scroll
110
- **scrollPropertyTop**: CSS property name for vertical scroll
111

112
## Debug Mode
113

114
```typescript { .api }
115
let debug: boolean | 1 | 2;
116
```
117

118
Controls debug output to the console:
119
- **false**: No debug output (default)
120
- **true** or **1**: Basic debug information
121
- **2**: Verbose debug information
122

123
## Mock Mode
124

125
```typescript { .api }
126
let mock: boolean;
127
```
128

129
In mock mode, all animations complete immediately on the next frame. Useful for testing and automated scenarios.
130

131
## Object Patching
132

133
```typescript { .api }
134
function patch(target: any, addGlobal?: boolean): void;
135
```
136

137
Patches objects to add Velocity chaining capabilities. Automatically patches common libraries and DOM prototypes.
138

139
### Auto-Patched Objects
140
- **window**: Global Velocity access
141
- **Element.prototype**: Element chaining support
142
- **NodeList.prototype**: NodeList chaining support
143
- **HTMLCollection.prototype**: HTMLCollection chaining support
144
- **jQuery.fn**: jQuery plugin integration (if jQuery is present)
145
- **Zepto.fn**: Zepto plugin integration (if Zepto is present)
146

147
## Registry Objects
148

149
### Actions Registry
150

151
```typescript { .api }
152
const Actions: { [name: string]: VelocityActionFn };
153
```
154

155
Registry of all available action functions. Can be extended with custom actions.
156

157
### Easings Registry
158

159
```typescript { .api }
160
const Easings: { [name: string]: VelocityEasingFn };
161
```
162

163
Registry of all available easing functions. Can be extended with custom easings.
164

165
### Sequences Registry
166

167
```typescript { .api }
168
const Sequences: { [name: string]: SequenceList };
169
```
170

171
Registry of all available animation sequences. Can be extended with custom sequences.
172

173
## Usage Examples
174

175
### Modifying Default Options
176

177
```typescript
178
import Velocity from "velocity-animate";
179

180
// Change global defaults
181
Velocity.defaults.duration = 800;
182
Velocity.defaults.easing = "easeOutQuad";
183
Velocity.defaults.queue = "myQueue";
184

185
// All subsequent animations will use these defaults
186
Velocity(element, { opacity: 0 }); // Uses 800ms duration and easeOutQuad
187

188
// Reset defaults to original values
189
Velocity.defaults.reset?.();
190
```
191

192
### Debug Mode
193

194
```typescript
195
// Enable basic debugging
196
Velocity.debug = true;
197

198
// Enable verbose debugging
199
Velocity.debug = 2;
200

201
// Animations will now log information to console
202
Velocity(element, { translateX: "200px" }, 1000);
203

204
// Disable debugging
205
Velocity.debug = false;
206
```
207

208
### Mock Mode for Testing
209

210
```typescript
211
// Enable mock mode
212
Velocity.mock = true;
213

214
// This animation will complete immediately
215
Velocity(element, { opacity: 0 }, 2000)
216
  .then(() => {
217
    console.log("Animation completed immediately!");
218
  });
219

220
// Disable mock mode
221
Velocity.mock = false;
222
```
223

224
### Custom Actions
225

226
```typescript
227
// Register a custom action
228
Velocity.Actions.customAction = function(args, elements, promise) {
229
  // Custom action implementation
230
  elements.forEach(element => {
231
    element.style.backgroundColor = "red";
232
  });
233
  return promise.resolve(elements);
234
};
235

236
// Use the custom action
237
Velocity(element, "customAction");
238
```
239

240
### Custom Easings
241

242
```typescript
243
// Register a custom easing function
244
Velocity.Easings.myEasing = function(t, b, c, d) {
245
  // t = current time, b = start value, c = change, d = duration
246
  return c * (t /= d) * t * t + b; // Cubic ease-in
247
};
248

249
// Use the custom easing
250
Velocity(element, { translateX: "200px" }, {
251
  duration: 1000,
252
  easing: "myEasing"
253
});
254
```
255

256
### Custom Sequences
257

258
```typescript
259
// Register a custom sequence
260
Velocity.Sequences.wobbleIn = {
261
  duration: 1000,
262
  0: { 
263
    rotateZ: "-45deg",
264
    scale: 0.3,
265
    opacity: 0
266
  },
267
  25: {
268
    rotateZ: "20deg",
269
    scale: 0.7,
270
    opacity: 0.7
271
  },
272
  75: {
273
    rotateZ: "-5deg",
274
    scale: 1.1,
275
    opacity: 1
276
  },
277
  100: {
278
    rotateZ: "0deg",
279
    scale: 1,
280
    opacity: 1
281
  }
282
};
283

284
// Use the custom sequence
285
Velocity(element, "wobbleIn");
286
```
287

288
### Object Patching
289

290
```typescript
291
// Patch a custom object for chaining
292
const myObject = {
293
  elements: document.querySelectorAll(".my-elements"),
294
  length: 3
295
};
296

297
Velocity.patch(myObject);
298

299
// Now myObject supports chaining
300
myObject.velocity({ opacity: 0.5 }, 500);
301
```
302

303
### State Inspection
304

305
```typescript
306
// Check environment
307
if (Velocity.State.isMobile) {
308
  // Use mobile-optimized animations
309
  Velocity(element, { translateX: "100px" }, { duration: 300 });
310
} else {
311
  // Use desktop animations
312
  Velocity(element, { translateX: "200px" }, { duration: 600 });
313
}
314

315
// Check browser support
316
if (Velocity.State.isChrome) {
317
  // Use Chrome-specific optimizations
318
}
319

320
// Inspect active animations
321
console.log(`Active animations: ${Velocity.State.calls.length}`);
322
```
323

324
### Global Configuration
325

326
```typescript
327
// Configure for performance
328
Velocity.defaults.mobileHA = true;  // Enable hardware acceleration
329
Velocity.defaults.cache = true;    // Cache computed styles
330

331
// Configure for accessibility
332
Velocity.defaults.duration = 200;  // Shorter animations
333
Velocity.mock = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
334

335
// Configure for development
336
if (process.env.NODE_ENV === 'development') {
337
  Velocity.debug = 1;
338
}
339
```
340

341
### Cleanup and Memory Management
342

343
```typescript
344
// Stop all animations and clear state
345
Velocity(document.querySelectorAll("*"), "stop", true);
346

347
// Check for memory leaks in development
348
if (Velocity.debug) {
349
  setInterval(() => {
350
    console.log(`Active calls: ${Velocity.State.calls.length}`);
351
  }, 5000);
352
}
353
```