tessl/npm-velocity-animate

High-performance JavaScript animation library with TypeScript support providing DOM animations, transforms, UI effects, and comprehensive easing functions.

—

Pending

Overview

Eval results

Files

Core Animation

Name: tessl/npm-velocity-animate
Author: tessl

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

Main Animation Function

function Velocity(
  elements: VelocityElements,
  properties: Properties<any>,
  options?: VelocityOptions
): VelocityResult;

function Velocity(
  elements: VelocityElements,
  properties: Properties<any>, 
  duration?: number,
  complete?: VelocityCallbackFn
): VelocityResult;

function Velocity(
  elements: VelocityElements,
  properties: Properties<any>,
  easing?: VelocityEasingType,
  complete?: VelocityCallbackFn  
): VelocityResult;

function Velocity(
  elements: VelocityElements,
  properties: Properties<any>,
  duration?: number,
  easing?: VelocityEasingType,
  complete?: VelocityCallbackFn
): VelocityResult;

Animation Options

interface VelocityOptions {
  duration?: number | "fast" | "normal" | "slow";
  easing?: VelocityEasingType;
  queue?: string | false;
  begin?: VelocityCallbackFn;
  progress?: VelocityProgressFn;
  complete?: VelocityCallbackFn;
  display?: string | "auto" | "inline" | "block" | "inline-block" | "flex" | "none";
  visibility?: "hidden" | "visible" | "collapse";
  loop?: boolean | number;
  delay?: number | "fast" | "normal" | "slow";
  mobileHA?: boolean;
  drag?: boolean;
  backwards?: boolean;
  cache?: boolean;
  promiseRejectEmpty?: boolean;
  repeatAgain?: boolean;
  stagger?: number | VelocityOptionFn<number>;
  sync?: boolean;
  tween?: string;
  fpsLimit?: number;
  minFrameTime?: number;
  promise?: boolean;
  repeat?: boolean | number;
  speed?: number;
}

interface StrictVelocityOptions extends VelocityOptions {
  duration: number; 
  easing: VelocityEasingFn;
  queue: string | false;
  begin: VelocityCallbackFn | undefined;
  progress: VelocityProgressFn | undefined;
  complete: VelocityCallbackFn | undefined;
  delay: number;
  loop: boolean | number;
  repeatAgain: boolean;
}

Property Types

type Properties<T> = {
  "clientHeight"?: T;
  "clientWidth"?: T;
  "innerHeight"?: T;
  "innerWidth"?: T;
  "outerHeight"?: T;
  "outerWidth"?: T;
  "scroll"?: T;
  "scrollHeight"?: T;
  "scrollLeft"?: T;
  "scrollTop"?: T;
  "scrollWidth"?: T;
  "tween"?: T;
} & {
  [property in keyof CSSStyleDeclaration]?: T;
} & {
  [property: string]: T;
};

type VelocityPropertyValue = 
  | string 
  | number 
  | VelocityPropertyValueFn
  | [VelocityPropertyValue]
  | [VelocityPropertyValue, VelocityEasingType | number | string]
  | [VelocityPropertyValue, VelocityEasingType, number | string];

type VelocityPropertyValueFn = (
  element: HTMLorSVGElement,
  index: number,
  elements: HTMLorSVGElement[]
) => VelocityPropertyValue;

Element Types

type VelocityElements = 
  | HTMLorSVGElement
  | HTMLorSVGElement[]
  | NodeList
  | HTMLCollection
  | VelocityResult
  | string;

type HTMLorSVGElement = HTMLElement | SVGElement;

Result Type

interface VelocityResult extends Array<HTMLorSVGElement> {
  velocity: typeof Velocity;
  readonly promise?: Promise<HTMLorSVGElement[] & VelocityResult>;
  then?: (resolve: (value?: any) => void, reject?: (reason?: any) => void) => VelocityResult;
  catch?: (reject: (reason?: any) => void) => VelocityResult;
  finally?: (callback: () => void) => VelocityResult;
}

Callback Function Types

type VelocityCallbackFn = (
  this: VelocityResult,
  elements?: VelocityResult,
  activeCall?: AnimationCall
) => void;

type VelocityProgressFn = (
  this: VelocityResult,
  elements?: VelocityResult,
  percentComplete?: number,
  remaining?: number,
  tweenValue?: number,
  activeCall?: AnimationCall
) => void;

Usage Examples

Basic Property Animation

import Velocity from "velocity-animate";

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

// Animate multiple properties
Velocity(element, {
  translateX: "200px",
  rotateZ: "45deg",
  scale: 1.2
}, 800);

Transform Properties

// 2D Transforms
Velocity(element, {
  translateX: "100px",
  translateY: "-50px", 
  rotateZ: "90deg",
  scaleX: 1.5,
  scaleY: 0.8,
  skewX: "15deg",
  skewY: "5deg"
});

// 3D Transforms  
Velocity(element, {
  translateZ: "200px",
  rotateX: "45deg",
  rotateY: "30deg", 
  perspective: "1000px"
});

Property Value Functions

// Dynamic values based on element index
Velocity(elements, {
  translateX: (element, index) => `${index * 50}px`,
  opacity: (element, index, elements) => 1 - (index / elements.length)
}, 1000);

Array-Based Values

// From-to values: [from, to]
Velocity(element, {
  translateX: ["0px", "200px"],
  opacity: [1, 0.3]
});

// From-to-easing values: [from, to, easing]
Velocity(element, {
  translateX: ["0px", "200px", "easeInOutQuad"],
  rotateZ: ["0deg", "360deg", "easeOutBounce"]
});

Chaining Animations

// Promise-based chaining
Velocity(element, { translateX: "200px" }, 500)
  .then(() => Velocity(element, { rotateZ: "180deg" }, 300))
  .then(() => Velocity(element, { scale: 0.5 }, 400));

// Sequential with different elements
Velocity(element1, { opacity: 0 }, 300)
  .then(() => Velocity(element2, { opacity: 1 }, 300));

Advanced Options

// With comprehensive options
Velocity(element, 
  { translateX: "300px", rotateY: "180deg" },
  {
    duration: 1200,
    easing: "easeInOutElastic", 
    delay: 200,
    loop: 2,
    display: "block",
    begin: (elements) => console.log("Animation started"),
    progress: (elements, percentComplete) => {
      console.log(`${Math.round(percentComplete * 100)}% complete`);
    },
    complete: (elements) => console.log("Animation finished")
  }
);

Staggered Animations

// Stagger with delay between elements
Velocity(elements, 
  { translateY: "-100px", opacity: 1 },
  { 
    duration: 600,
    stagger: 150  // 150ms delay between each element
  }
);

// Stagger with percentage-based delay
Velocity(elements, 
  { scale: 1.2 },
  { 
    duration: 800,
    stagger: "25%"  // 25% of duration delay between elements
  }
);

Mock Mode

// Enable mock mode for testing
Velocity.mock = true;

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

Install with Tessl CLI