@zakkster/lite-physics

Spring-based DOM animation with velocity handoff. Magnetic hover, draggable cards, Tinder-style swipe.

→ Live Recipes Gallery Demo

→ Live Recipes Gallery Demo vol.2

100 springs share 1 RAF loop. Zero rAF spam. Zero GC.

Why lite-physics?

| Feature | lite-physics | Framer Motion | React Spring | GSAP Draggable | |---|---|---|---|---| | Shared Ticker | Yes (1 RAF for all) | No | No | No | | Velocity handoff | Yes (measured) | Approximate | No | No | | Swipe-to-dismiss | Yes (built-in) | Manual | No | Manual | | Framework-free | Yes | React only | React only | jQuery-era | | Spring physics | Yes | Yes | Yes | No | | Zero-GC | Yes | No | No | No | | Bundle size | < 3KB | ~30KB | ~20KB | ~25KB |

Installation

npm install @zakkster/lite-physics

Quick Start

Magnetic Hover Card

import { springCard } from '@zakkster/lite-physics';

const card = springCard('.product-card', {
    stiffness: 220,
    damping: 24,
    strength: 0.2, // 20% follow cursor
});

// Later: card.destroy()

Animate a CSS Property

import { springStyle } from '@zakkster/lite-physics';

const opacity = springStyle('#modal', 'opacity', { stiffness: 200, damping: 30, initialValue: 0 });
const scale = springStyle('#modal', 'transform', { stiffness: 180, damping: 22, initialValue: 0.8, template: v => `scale(${v})` });

opacity.set(1);
scale.set(1);

Draggable Card with Velocity Handoff

import { draggableSpringCard } from '@zakkster/lite-physics';

const draggable = draggableSpringCard('.card', {
    stiffness: 150,
    damping: 18,
    rotationFactor: 0.05,
    onRelease: ({ vx, vy }) => console.log('Flick speed:', vx),
});

Tinder-Style Swipe

import { swipeCard } from '@zakkster/lite-physics';

const swipe = swipeCard('.dating-card', {
    swipeThreshold: 100,
    velocityThreshold: 500,
    onSwipeLeft: (el) => console.log('Nope'),
    onSwipeRight: (el) => console.log('Like!'),
    removeOnSwipe: true,
});

Recipes

const cards = document.querySelectorAll('.card');
cards.forEach((card, i) => {
    card.style.zIndex = cards.length - i;
    swipeCard(card, {
        onSwipeRight: () => handleLike(i),
        onSwipeLeft: () => handleDislike(i),
    });
});

const counter = springStyle('#price', 'textContent', {
    stiffness: 120, damping: 20, initialValue: 0,
    template: v => `$${Math.round(v)}`,
});
counter.set(99);

API

| Export | Description | |---|---| | springStyle(el, prop, options) | Animate any CSS property with spring physics | | springCard(el, options) | 2D magnetic hover (Apple TV style) | | draggableSpringCard(el, options) | Drag with velocity handoff on release | | swipeCard(el, options) | Tinder-style swipe-to-dismiss |

All return { destroy() } for SPA cleanup.

License

MIT