0
# Velocity Animate
1

2
Velocity is a high-performance JavaScript animation library that provides accelerated DOM animation, CSS transforms, color animations, scroll animations, and physics-based easing. Built with TypeScript, it offers comprehensive animation capabilities with zero dependencies and cross-browser compatibility, serving as a modern alternative to jQuery animations.
3

4
## Package Information
5

6
- **Package Name**: velocity-animate
7
- **Package Type**: npm
8
- **Language**: TypeScript/JavaScript
9
- **Installation**: `npm install velocity-animate`
10

11
## Core Imports
12

13
```typescript
14
import Velocity from "velocity-animate";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const Velocity = require("velocity-animate");
21
```
22

23
For ES6 named imports:
24

25
```typescript
26
import { Velocity } from "velocity-animate";
27
```
28

29
For TypeScript with types:
30

31
```typescript
32
import Velocity, { VelocityOptions, VelocityResult } from "velocity-animate";
33
```
34

35
## Basic Usage
36

37
```typescript
38
import Velocity from "velocity-animate";
39

40
// Basic animation - fade in an element
41
Velocity(element, { opacity: 1 }, { duration: 1000 });
42

43
// Chain multiple animations
44
Velocity(element, { translateX: "200px" }, { duration: 500 })
45
  .then(() => Velocity(element, { rotateZ: "45deg" }, { duration: 300 }));
46

47
// Use predefined UI sequences
48
Velocity(element, "fadeIn", { duration: 600 });
49

50
// Method chaining (when patched)
51
element.velocity({ left: "200px" }, 1000)
52
       .velocity({ rotateY: "45deg" }, 500);
53
```
54

55
## Architecture
56

57
Velocity is organized around several core systems:
58

59
- **Animation Engine**: Core tweening system with optimized performance and hardware acceleration
60
- **Property System**: CSS and transform property normalization with cross-browser compatibility  
61
- **Easing Functions**: Comprehensive easing library with 30+ functions including physics-based options
62
- **Action System**: Animation control actions (pause, resume, stop, reverse, etc.)
63
- **Sequence System**: Pre-built animation sequences and custom sequence registration
64
- **UI Effects Pack**: 78 pre-built animation effects for common interface patterns
65
- **Promise Support**: Native promise integration for modern async/await workflows
66

67
## Capabilities
68

69
### Core Animation
70

71
Primary animation functionality for CSS properties, transforms, and custom properties. Supports chaining, promises, and advanced timing control.
72

73
```typescript { .api }
74
function Velocity(
75
  elements: VelocityElements,
76
  properties: Properties<any>,
77
  options?: VelocityOptions
78
): VelocityResult;
79

80
function Velocity(
81
  elements: VelocityElements, 
82
  properties: Properties<any>,
83
  duration?: number,
84
  complete?: VelocityCallbackFn
85
): VelocityResult;
86
```
87

88
[Core Animation](./core-animation.md)
89

90
### Animation Actions
91

92
Control and introspection actions for managing running animations, getting/setting properties, and animation state management.
93

94
```typescript { .api }
95
function Velocity(elements: VelocityElements, action: "stop", queue?: string): VelocityResult;
96
function Velocity(elements: VelocityElements, action: "pause"): VelocityResult;
97
function Velocity(elements: VelocityElements, action: "resume"): VelocityResult;
98
function Velocity(elements: VelocityElements, action: "finish", queue?: string): VelocityResult;
99
function Velocity(elements: VelocityElements, action: "reverse"): VelocityResult;
100
```
101

102
[Animation Actions](./actions.md)
103

104
### Easing Functions
105

106
Comprehensive easing function library including linear, swing, CSS standard easings, and physics-based easings for natural motion.
107

108
```typescript { .api }
109
interface VelocityEasings {
110
  linear: VelocityEasingFn;
111
  swing: VelocityEasingFn;
112
  ease: VelocityEasingFn;
113
  "ease-in": VelocityEasingFn;
114
  "ease-out": VelocityEasingFn;
115
  "ease-in-out": VelocityEasingFn;
116
  // ... 30+ total easing functions
117
}
118
```
119

120
[Easing Functions](./easings.md)
121

122
### UI Animation Sequences  
123

124
Pre-built animation sequences organized into categories like attention seekers, entrances, exits, and special effects. Perfect for common interface animations.
125

126
```typescript { .api }
127
function Velocity(
128
  elements: VelocityElements,
129
  sequence: string,
130
  options?: VelocityOptions
131
): VelocityResult;
132

133
interface VelocitySequences {
134
  // Attention Seekers (10)
135
  bounce: SequenceList;
136
  flash: SequenceList;
137
  pulse: SequenceList;
138
  shake: SequenceList;
139
  // ... 78 total sequences
140
}
141
```
142

143
[UI Animation Sequences](./ui-sequences.md)
144

145
### Static Properties & Configuration
146

147
Global configuration options, state management, debugging tools, and utility functions for extending Velocity's capabilities.
148

149
```typescript { .api }
150
interface VelocityStatic {
151
  version: string;
152
  defaults: StrictVelocityOptions & { reset?: () => void };
153
  State: VelocityState;
154
  debug: boolean | 1 | 2;
155
  mock: boolean;
156
  patch: (target: any, addGlobal?: boolean) => void;
157
}
158
```
159

160
[Configuration & Utilities](./configuration.md)
161

162
## Types
163

164
Core interfaces and type definitions used throughout the Velocity API:
165

166
```typescript { .api }
167
interface VelocityOptions {
168
  duration?: number | "fast" | "normal" | "slow";
169
  easing?: VelocityEasingType;
170
  queue?: string | false;
171
  begin?: VelocityCallbackFn;
172
  progress?: VelocityProgressFn;
173
  complete?: VelocityCallbackFn;
174
  display?: string | "auto" | "inline" | "block" | "inline-block" | "flex" | "none";
175
  visibility?: "hidden" | "visible" | "collapse";
176
  loop?: boolean | number;
177
  delay?: number;
178
  mobileHA?: boolean;
179
}
180

181
interface VelocityResult extends Array<HTMLorSVGElement> {
182
  velocity: typeof Velocity;
183
  then?: (resolve: (value?: any) => void, reject?: (reason?: any) => void) => VelocityResult;
184
}
185

186
type VelocityElements = 
187
  | HTMLorSVGElement 
188
  | HTMLorSVGElement[] 
189
  | NodeList 
190
  | HTMLCollection 
191
  | VelocityResult 
192
  | string;
193

194
type HTMLorSVGElement = HTMLElement | SVGElement;
195
```