tessl/npm-velocity-animate
High-performance JavaScript animation library with TypeScript support providing DOM animations, transforms, UI effects, and comprehensive easing functions.
—
Pending
configuration.mddocs/
Configuration & Utilities
Velocity provides global configuration options, state management, debugging tools, and utility functions for extending and customizing its capabilities.
Static Properties
interface VelocityStatic {
version: string;
defaults: StrictVelocityOptions & { reset?: () => void };
State: VelocityState;
Actions: { [name: string]: VelocityActionFn };
Easings: { [name: string]: VelocityEasingFn };
Sequences: { [name: string]: SequenceList };
patch: (target: any, addGlobal?: boolean) => void;
debug: boolean | 1 | 2;
mock: boolean;
}Version Information
const version: string;The current version of Velocity as a string (e.g., "2.0.6").
Default Options
interface VelocityDefaults extends StrictVelocityOptions {
reset?: () => void;
}
const defaults: VelocityDefaults;Global default options applied to all animations. Can be modified to change behavior across the entire application.
Default Values
const defaultOptions = {
duration: 400, // milliseconds
easing: "swing", // default easing function
queue: "", // default queue name
begin: undefined, // begin callback
progress: undefined, // progress callback
complete: undefined, // complete callback
display: undefined, // CSS display value
visibility: undefined, // CSS visibility value
loop: false, // loop count or boolean
delay: 0, // delay before animation starts
mobileHA: true, // mobile hardware acceleration
// ... other options
};State Management
interface VelocityState {
isClient: boolean;
isMobile: boolean;
isGingerbread: boolean;
isChrome: boolean;
isFirefox: boolean;
prefixElement: HTMLElement;
prefixMatches: { [property: string]: string };
calls: AnimationCall[];
first?: AnimationCall;
last?: AnimationCall;
firstNew?: AnimationCall;
readonly windowScrollAnchor: boolean;
readonly scrollAnchor: Window | HTMLElement | Node | boolean;
readonly scrollPropertyLeft: string;
readonly scrollPropertyTop: string;
readonly className: string;
isTicking: boolean;
}
const State: VelocityState;State Properties
Environment Detection
- isClient: True if running in a browser environment
- isMobile: True if running on a mobile device
- isGingerbread: True if running on Android 2.3 (Gingerbread)
- isChrome: True if running in Chrome browser
- isFirefox: True if running in Firefox browser
CSS Prefix Management
- prefixElement: Element used for CSS prefix detection
- prefixMatches: Map of CSS properties to their prefixed versions
- className: CSS class name used for styling
Animation Queue Management
- calls: Array of all active animation calls
- first: First animation call in the queue (optional)
- last: Last animation call in the queue (optional)
- firstNew: First new animation call to be processed (optional)
- isTicking: Whether the animation ticker is currently running
Scroll Management
- windowScrollAnchor: Whether to use window as scroll anchor
- scrollAnchor: Element or window to use as scroll reference
- scrollPropertyLeft: CSS property name for horizontal scroll
- scrollPropertyTop: CSS property name for vertical scroll
Debug Mode
let debug: boolean | 1 | 2;Controls debug output to the console:
- false: No debug output (default)
- true or 1: Basic debug information
- 2: Verbose debug information
Mock Mode
let mock: boolean;In mock mode, all animations complete immediately on the next frame. Useful for testing and automated scenarios.
Object Patching
function patch(target: any, addGlobal?: boolean): void;Patches objects to add Velocity chaining capabilities. Automatically patches common libraries and DOM prototypes.
Auto-Patched Objects
- window: Global Velocity access
- Element.prototype: Element chaining support
- NodeList.prototype: NodeList chaining support
- HTMLCollection.prototype: HTMLCollection chaining support
- jQuery.fn: jQuery plugin integration (if jQuery is present)
- Zepto.fn: Zepto plugin integration (if Zepto is present)
Registry Objects
Actions Registry
const Actions: { [name: string]: VelocityActionFn };Registry of all available action functions. Can be extended with custom actions.
Easings Registry
const Easings: { [name: string]: VelocityEasingFn };Registry of all available easing functions. Can be extended with custom easings.
Sequences Registry
const Sequences: { [name: string]: SequenceList };Registry of all available animation sequences. Can be extended with custom sequences.
Usage Examples
Modifying Default Options
import Velocity from "velocity-animate";
// Change global defaults
Velocity.defaults.duration = 800;
Velocity.defaults.easing = "easeOutQuad";
Velocity.defaults.queue = "myQueue";
// All subsequent animations will use these defaults
Velocity(element, { opacity: 0 }); // Uses 800ms duration and easeOutQuad
// Reset defaults to original values
Velocity.defaults.reset?.();Debug Mode
// Enable basic debugging
Velocity.debug = true;
// Enable verbose debugging
Velocity.debug = 2;
// Animations will now log information to console
Velocity(element, { translateX: "200px" }, 1000);
// Disable debugging
Velocity.debug = false;Mock Mode for Testing
// Enable mock mode
Velocity.mock = true;
// This animation will complete immediately
Velocity(element, { opacity: 0 }, 2000)
.then(() => {
console.log("Animation completed immediately!");
});
// Disable mock mode
Velocity.mock = false;Custom Actions
// Register a custom action
Velocity.Actions.customAction = function(args, elements, promise) {
// Custom action implementation
elements.forEach(element => {
element.style.backgroundColor = "red";
});
return promise.resolve(elements);
};
// Use the custom action
Velocity(element, "customAction");Custom Easings
// Register a custom easing function
Velocity.Easings.myEasing = function(t, b, c, d) {
// t = current time, b = start value, c = change, d = duration
return c * (t /= d) * t * t + b; // Cubic ease-in
};
// Use the custom easing
Velocity(element, { translateX: "200px" }, {
duration: 1000,
easing: "myEasing"
});Custom Sequences
// Register a custom sequence
Velocity.Sequences.wobbleIn = {
duration: 1000,
0: {
rotateZ: "-45deg",
scale: 0.3,
opacity: 0
},
25: {
rotateZ: "20deg",
scale: 0.7,
opacity: 0.7
},
75: {
rotateZ: "-5deg",
scale: 1.1,
opacity: 1
},
100: {
rotateZ: "0deg",
scale: 1,
opacity: 1
}
};
// Use the custom sequence
Velocity(element, "wobbleIn");Object Patching
// Patch a custom object for chaining
const myObject = {
elements: document.querySelectorAll(".my-elements"),
length: 3
};
Velocity.patch(myObject);
// Now myObject supports chaining
myObject.velocity({ opacity: 0.5 }, 500);State Inspection
// Check environment
if (Velocity.State.isMobile) {
// Use mobile-optimized animations
Velocity(element, { translateX: "100px" }, { duration: 300 });
} else {
// Use desktop animations
Velocity(element, { translateX: "200px" }, { duration: 600 });
}
// Check browser support
if (Velocity.State.isChrome) {
// Use Chrome-specific optimizations
}
// Inspect active animations
console.log(`Active animations: ${Velocity.State.calls.length}`);Global Configuration
// Configure for performance
Velocity.defaults.mobileHA = true; // Enable hardware acceleration
Velocity.defaults.cache = true; // Cache computed styles
// Configure for accessibility
Velocity.defaults.duration = 200; // Shorter animations
Velocity.mock = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
// Configure for development
if (process.env.NODE_ENV === 'development') {
Velocity.debug = 1;
}Cleanup and Memory Management
// Stop all animations and clear state
Velocity(document.querySelectorAll("*"), "stop", true);
// Check for memory leaks in development
if (Velocity.debug) {
setInterval(() => {
console.log(`Active calls: ${Velocity.State.calls.length}`);
}, 5000);
}Install with Tessl CLI
npx tessl i tessl/npm-velocity-animate