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

Animation Actions

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

Animation actions provide control and introspection capabilities for managing running animations, getting/setting properties, and controlling animation flow.

Control Actions

Stop Action

function Velocity(elements: VelocityElements, action: "stop"): VelocityResult;
function Velocity(elements: VelocityElements, action: "stop", queue: string): VelocityResult;
function Velocity(elements: VelocityElements, action: "stop", clearQueue: true): VelocityResult;
function Velocity(elements: VelocityElements, action: "stop", queue: string | false, stopAll: true): VelocityResult;
function Velocity(action: "stop", queue?: string | false, stopAll?: true): VelocityResult;

Stops running animations on elements (or globally if no elements specified). Optionally specify a queue name to stop only animations in that queue, or pass true for stopAll to clear all queued animations.

Pause Action

function Velocity(elements: VelocityElements, action: "pause"): VelocityResult;
function Velocity(elements: VelocityElements, action: "pause", queue: string): VelocityResult;
function Velocity(action: "pause", queue?: string): VelocityResult;

Pauses all running animations on the specified elements (or globally if no elements specified). Animations can be resumed later. Optionally specify a queue name to pause only animations in that queue.

Resume Action

function Velocity(elements: VelocityElements, action: "resume"): VelocityResult;
function Velocity(elements: VelocityElements, action: "resume", queue: string): VelocityResult;
function Velocity(action: "resume", queue?: string): VelocityResult;

Resumes previously paused animations on the specified elements (or globally if no elements specified). Optionally specify a queue name to resume only animations in that queue.

Finish Action

function Velocity(elements: VelocityElements, action: "finish"): VelocityResult;
function Velocity(elements: VelocityElements, action: "finish", queue: string): VelocityResult;

Immediately completes running animations, jumping to their end states. Optionally specify a queue name.

Reverse Action

function Velocity(elements: VelocityElements, action: "reverse"): VelocityResult;

Reverses the direction of running animations. If no animations are running, reverses the most recent animation.

Property Actions

Style Action

function Velocity(elements: VelocityElements, action: "style", property: string): string;
function Velocity(
  elements: VelocityElements, 
  action: "style", 
  properties: {[property: string]: VelocityPropertyValue}
): VelocityResult;

Gets or sets CSS style properties. When getting, returns the computed style value. When setting, applies the properties immediately.

Property Action

function Velocity(elements: VelocityElements, action: "property", property: string): any;
function Velocity(
  elements: VelocityElements,
  action: "property", 
  properties: {[property: string]: any}
): VelocityResult;

Gets or sets element properties (not CSS styles). Useful for accessing DOM properties like scrollTop, scrollLeft, etc.

Utility Actions

Option Action

function Velocity(elements: VelocityElements, action: "option", option: string): any;
function Velocity(
  elements: VelocityElements,
  action: "option",
  options: {[option: string]: any}
): VelocityResult;

Gets or sets animation options on running animations. Available options include all VelocityOptions properties.

Tween Action

function Velocity(
  elements: VelocityElements,
  action: "tween",
  properties: Properties<any>,
  progress: number
): VelocityResult;

Calculates intermediate property values at a specific progress point (0-1) without creating an animation.

Registration Actions

Register Easing Action

function Velocity(action: "registerEasing", name: string, easing: VelocityEasingFn): void;

Registers a custom easing function for use throughout the application.

Register Normalization Action

function Velocity(
  action: "registerNormalization",
  constructor: {new: () => Element} | string,
  name: string,
  normalization: VelocityNormalizationsFn,
  unit?: string,
  cache?: boolean
): void;

function Velocity(
  action: "registerNormalization",
  constructor: {new: () => Element} | string,
  name: string,
  normalization: VelocityNormalizationsFn,
  cache?: boolean
): void;

Registers a custom normalization handler for CSS properties. This is the interface between Velocity and the actual properties.

Register Sequence Action

function Velocity(action: "registerSequence", name: string, sequence: VelocitySequence): void;
function Velocity(action: "registerSequence", sequences: {[name: string]: VelocitySequence}): void;

Registers custom animation sequences for use throughout the application.

Has Normalization Action

function Velocity(
  action: "hasNormalization",
  constructor: {new: () => Element} | string,
  name: string
): boolean;

Checks if there is a normalization handler for the named type of Element and property.

Usage Examples

Animation Control

import Velocity from "velocity-animate";

const element = document.getElementById("myElement");

// Start an animation
Velocity(element, { translateX: "200px" }, { duration: 2000 });

// Stop the animation
Velocity(element, "stop");

// Start another animation
Velocity(element, { rotateZ: "360deg" }, { duration: 3000 });

// Pause it
Velocity(element, "pause");

// Resume it later
setTimeout(() => {
  Velocity(element, "resume");
}, 1000);

// Or finish it immediately
Velocity(element, "finish");

Queue Management

// Queue multiple animations
Velocity(element, { translateX: "100px" }, { queue: "slideQueue" });
Velocity(element, { translateY: "100px" }, { queue: "slideQueue" });
Velocity(element, { rotateZ: "90deg" }, { queue: "rotateQueue" });

// Stop only animations in slideQueue
Velocity(element, "stop", "slideQueue");

// Stop all animations and clear all queues
Velocity(element, "stop", true);

Reverse Animation

// Start animation
Velocity(element, { 
  translateX: "300px",
  rotateZ: "180deg",
  scale: 1.5
}, 1500);

// Reverse it mid-animation
setTimeout(() => {
  Velocity(element, "reverse");
}, 750);

Property Getting/Setting

// Get computed CSS style
const opacity = Velocity(element, "style", "opacity");
const transform = Velocity(element, "style", "transform");

// Set CSS styles immediately
Velocity(element, "style", {
  opacity: 0.5,
  backgroundColor: "#ff0000",
  display: "block"
});

// Get DOM properties
const scrollTop = Velocity(element, "property", "scrollTop");
const offsetWidth = Velocity(element, "property", "offsetWidth");

// Set DOM properties
Velocity(element, "property", {
  scrollTop: 100,
  textContent: "New content"
});

Option Inspection

// Start animation with options
Velocity(element, { translateX: "200px" }, {
  duration: 2000,
  easing: "easeInOutQuad",
  loop: 3
});

// Get current options
const duration = Velocity(element, "option", "duration");
const easing = Velocity(element, "option", "easing");
const loop = Velocity(element, "option", "loop");

// Modify options on running animation
Velocity(element, "option", {
  duration: 3000,  // Extend the animation
  loop: 5         // Increase loop count
});

Tween Calculation

// Calculate intermediate values without animating
Velocity(element, "tween", {
  translateX: "200px",
  opacity: 0.5,
  scale: 1.2
}, 0.5); // 50% progress

// Useful for custom animation loops or progress bars
for (let i = 0; i <= 100; i += 10) {
  const progress = i / 100;
  Velocity(element, "tween", {
    rotateZ: "360deg",
    scale: [1, 2]
  }, progress);
  
  // element now has properties set to the calculated intermediate values
  console.log(`Progress: ${i}%, Rotation: ${element.style.transform}`);
}

Multiple Elements

const elements = document.querySelectorAll(".animated");

// Control all elements at once
Velocity(elements, { translateY: "50px" }, 1000);

// Pause all
Velocity(elements, "pause");

// Resume all
Velocity(elements, "resume");

// Stop all and clear queues
Velocity(elements, "stop", true);

// Set styles on all elements
Velocity(elements, "style", { opacity: 0.8 });

Registration Actions

// Register a custom easing function
Velocity("registerEasing", "myCustomEasing", function(t, b, c, d) {
  // t = current time, b = start value, c = change, d = duration
  return c * t / d + b; // Linear easing
});

// Use the registered easing
Velocity(element, { translateX: "200px" }, {
  duration: 1000,
  easing: "myCustomEasing"
});

// Register a custom animation sequence
Velocity("registerSequence", "customBounce", {
  duration: 1000,
  "0%": { transform: "translateY(0px)" },
  "50%": { transform: "translateY(-30px)" },
  "100%": { transform: "translateY(0px)" }
});

// Register multiple sequences at once
Velocity("registerSequence", {
  "wiggle": {
    duration: 500,
    "0%": { transform: "rotate(0deg)" },
    "25%": { transform: "rotate(5deg)" },
    "75%": { transform: "rotate(-5deg)" },
    "100%": { transform: "rotate(0deg)" }
  },
  "shake": {
    duration: 600,
    "0%": { transform: "translateX(0px)" },
    "25%": { transform: "translateX(-10px)" },
    "75%": { transform: "translateX(10px)" },
    "100%": { transform: "translateX(0px)" }
  }
});

// Use registered sequences
Velocity(element, "customBounce");
Velocity(element, "wiggle");

// Check if normalization exists
const hasOpacity = Velocity("hasNormalization", "HTMLElement", "opacity");
if (hasOpacity) {
  console.log("Opacity normalization is available");
}

Install with Tessl CLI