0
# Core Animation
1

2
The core animation functionality provides the primary interface for animating CSS properties, transforms, and custom properties with high performance and extensive configuration options.
3

4
## Main Animation Function
5

6
```typescript { .api }
7
function Velocity(
8
  elements: VelocityElements,
9
  properties: Properties<any>,
10
  options?: VelocityOptions
11
): VelocityResult;
12

13
function Velocity(
14
  elements: VelocityElements,
15
  properties: Properties<any>, 
16
  duration?: number,
17
  complete?: VelocityCallbackFn
18
): VelocityResult;
19

20
function Velocity(
21
  elements: VelocityElements,
22
  properties: Properties<any>,
23
  easing?: VelocityEasingType,
24
  complete?: VelocityCallbackFn  
25
): VelocityResult;
26

27
function Velocity(
28
  elements: VelocityElements,
29
  properties: Properties<any>,
30
  duration?: number,
31
  easing?: VelocityEasingType,
32
  complete?: VelocityCallbackFn
33
): VelocityResult;
34
```
35

36
## Animation Options
37

38
```typescript { .api }
39
interface VelocityOptions {
40
  duration?: number | "fast" | "normal" | "slow";
41
  easing?: VelocityEasingType;
42
  queue?: string | false;
43
  begin?: VelocityCallbackFn;
44
  progress?: VelocityProgressFn;
45
  complete?: VelocityCallbackFn;
46
  display?: string | "auto" | "inline" | "block" | "inline-block" | "flex" | "none";
47
  visibility?: "hidden" | "visible" | "collapse";
48
  loop?: boolean | number;
49
  delay?: number | "fast" | "normal" | "slow";
50
  mobileHA?: boolean;
51
  drag?: boolean;
52
  backwards?: boolean;
53
  cache?: boolean;
54
  promiseRejectEmpty?: boolean;
55
  repeatAgain?: boolean;
56
  stagger?: number | VelocityOptionFn<number>;
57
  sync?: boolean;
58
  tween?: string;
59
  fpsLimit?: number;
60
  minFrameTime?: number;
61
  promise?: boolean;
62
  repeat?: boolean | number;
63
  speed?: number;
64
}
65

66
interface StrictVelocityOptions extends VelocityOptions {
67
  duration: number; 
68
  easing: VelocityEasingFn;
69
  queue: string | false;
70
  begin: VelocityCallbackFn | undefined;
71
  progress: VelocityProgressFn | undefined;
72
  complete: VelocityCallbackFn | undefined;
73
  delay: number;
74
  loop: boolean | number;
75
  repeatAgain: boolean;
76
}
77
```
78

79
## Property Types
80

81
```typescript { .api }
82
type Properties<T> = {
83
  "clientHeight"?: T;
84
  "clientWidth"?: T;
85
  "innerHeight"?: T;
86
  "innerWidth"?: T;
87
  "outerHeight"?: T;
88
  "outerWidth"?: T;
89
  "scroll"?: T;
90
  "scrollHeight"?: T;
91
  "scrollLeft"?: T;
92
  "scrollTop"?: T;
93
  "scrollWidth"?: T;
94
  "tween"?: T;
95
} & {
96
  [property in keyof CSSStyleDeclaration]?: T;
97
} & {
98
  [property: string]: T;
99
};
100

101
type VelocityPropertyValue = 
102
  | string 
103
  | number 
104
  | VelocityPropertyValueFn
105
  | [VelocityPropertyValue]
106
  | [VelocityPropertyValue, VelocityEasingType | number | string]
107
  | [VelocityPropertyValue, VelocityEasingType, number | string];
108

109
type VelocityPropertyValueFn = (
110
  element: HTMLorSVGElement,
111
  index: number,
112
  elements: HTMLorSVGElement[]
113
) => VelocityPropertyValue;
114
```
115

116
## Element Types
117

118
```typescript { .api }
119
type VelocityElements = 
120
  | HTMLorSVGElement
121
  | HTMLorSVGElement[]
122
  | NodeList
123
  | HTMLCollection
124
  | VelocityResult
125
  | string;
126

127
type HTMLorSVGElement = HTMLElement | SVGElement;
128
```
129

130
## Result Type
131

132
```typescript { .api }
133
interface VelocityResult extends Array<HTMLorSVGElement> {
134
  velocity: typeof Velocity;
135
  readonly promise?: Promise<HTMLorSVGElement[] & VelocityResult>;
136
  then?: (resolve: (value?: any) => void, reject?: (reason?: any) => void) => VelocityResult;
137
  catch?: (reject: (reason?: any) => void) => VelocityResult;
138
  finally?: (callback: () => void) => VelocityResult;
139
}
140
```
141

142
## Callback Function Types
143

144
```typescript { .api }
145
type VelocityCallbackFn = (
146
  this: VelocityResult,
147
  elements?: VelocityResult,
148
  activeCall?: AnimationCall
149
) => void;
150

151
type VelocityProgressFn = (
152
  this: VelocityResult,
153
  elements?: VelocityResult,
154
  percentComplete?: number,
155
  remaining?: number,
156
  tweenValue?: number,
157
  activeCall?: AnimationCall
158
) => void;
159
```
160

161
## Usage Examples
162

163
### Basic Property Animation
164

165
```typescript
166
import Velocity from "velocity-animate";
167

168
// Animate opacity
169
Velocity(element, { opacity: 0.5 }, { duration: 1000 });
170

171
// Animate multiple properties
172
Velocity(element, {
173
  translateX: "200px",
174
  rotateZ: "45deg",
175
  scale: 1.2
176
}, 800);
177
```
178

179
### Transform Properties
180

181
```typescript
182
// 2D Transforms
183
Velocity(element, {
184
  translateX: "100px",
185
  translateY: "-50px", 
186
  rotateZ: "90deg",
187
  scaleX: 1.5,
188
  scaleY: 0.8,
189
  skewX: "15deg",
190
  skewY: "5deg"
191
});
192

193
// 3D Transforms  
194
Velocity(element, {
195
  translateZ: "200px",
196
  rotateX: "45deg",
197
  rotateY: "30deg", 
198
  perspective: "1000px"
199
});
200
```
201

202
### Property Value Functions
203

204
```typescript
205
// Dynamic values based on element index
206
Velocity(elements, {
207
  translateX: (element, index) => `${index * 50}px`,
208
  opacity: (element, index, elements) => 1 - (index / elements.length)
209
}, 1000);
210
```
211

212
### Array-Based Values
213

214
```typescript
215
// From-to values: [from, to]
216
Velocity(element, {
217
  translateX: ["0px", "200px"],
218
  opacity: [1, 0.3]
219
});
220

221
// From-to-easing values: [from, to, easing]
222
Velocity(element, {
223
  translateX: ["0px", "200px", "easeInOutQuad"],
224
  rotateZ: ["0deg", "360deg", "easeOutBounce"]
225
});
226
```
227

228
### Chaining Animations
229

230
```typescript
231
// Promise-based chaining
232
Velocity(element, { translateX: "200px" }, 500)
233
  .then(() => Velocity(element, { rotateZ: "180deg" }, 300))
234
  .then(() => Velocity(element, { scale: 0.5 }, 400));
235

236
// Sequential with different elements
237
Velocity(element1, { opacity: 0 }, 300)
238
  .then(() => Velocity(element2, { opacity: 1 }, 300));
239
```
240

241
### Advanced Options
242

243
```typescript
244
// With comprehensive options
245
Velocity(element, 
246
  { translateX: "300px", rotateY: "180deg" },
247
  {
248
    duration: 1200,
249
    easing: "easeInOutElastic", 
250
    delay: 200,
251
    loop: 2,
252
    display: "block",
253
    begin: (elements) => console.log("Animation started"),
254
    progress: (elements, percentComplete) => {
255
      console.log(`${Math.round(percentComplete * 100)}% complete`);
256
    },
257
    complete: (elements) => console.log("Animation finished")
258
  }
259
);
260
```
261

262
### Staggered Animations
263

264
```typescript
265
// Stagger with delay between elements
266
Velocity(elements, 
267
  { translateY: "-100px", opacity: 1 },
268
  { 
269
    duration: 600,
270
    stagger: 150  // 150ms delay between each element
271
  }
272
);
273

274
// Stagger with percentage-based delay
275
Velocity(elements, 
276
  { scale: 1.2 },
277
  { 
278
    duration: 800,
279
    stagger: "25%"  // 25% of duration delay between elements
280
  }
281
);
282
```
283

284
### Mock Mode
285

286
```typescript
287
// Enable mock mode for testing
288
Velocity.mock = true;
289

290
// All animations complete immediately on next frame
291
Velocity(element, { opacity: 0 }, 2000); // Completes in ~16ms
292
```