Skip to content
necromancer logoNecromancerUI
Lifecycle-owned Web Animations API primitives for native playback, groups, and additive FLIP transitions.
Version
v26.11.20
Size
2.4 KB gzip
Dependencies
Zero dependencies
Browser
animateanimateEachcaptureLayout

Why Necromancer? ​

Native Web Animations API calls do not provide lifecycle ownership, reduced-motion policy, grouped playback, or layout transitions. Necromancer retains native keyframes and timing semantics while making ownership explicit for a component or DOM feature.

ts
// Before
const animation = element.animate(keyframes, { duration: 180 });
animation.addEventListener('cancel', removeListeners);

// After
const animation = animate(element, keyframes, { duration: 180 });
animation.dispose();
FeatureNative WAAPINecromancerMotion One
Bundle size0 B2.4 KB~18 kB
Root dependencies
Lifecycle handleManualdispose()Library-specific controls
Reduced motionManualmotion: 'system' defaultConfiguration required
Layout transitionsManual FLIP mathcaptureLayout().animate()Separate API

Use Necromancer when you need native browser animations with explicit cancellation, reduced-motion behavior, staggered groups, or positional FLIP transitions.

Consider CSS transitions when a static style change needs no playback control, cleanup, or layout measurement.

Installation ​

sh
pnpm add @vielzeug/necromancer
sh
npm install @vielzeug/necromancer
sh
yarn add @vielzeug/necromancer

Quick Start ​

Start the animation after its DOM element mounts and release it when its UI owner is removed.

ts
import { animate } from '@vielzeug/necromancer';

const notice = document.createElement('p');
notice.textContent = 'Saved';
document.body.append(notice);

const animation = animate(
  notice,
  [
    { opacity: 0, transform: 'translateY(8px)' },
    { opacity: 1, transform: 'translateY(0)' },
  ],
  { duration: 180, easing: 'ease-out' },
);

await animation.result;
animation.dispose();

Features ​

  • animate(): Native element animation with lifecycle ownership and direct native access
  • animateEach(): Group ownership with stable keyframe factories and stagger
  • captureLayout(): One-shot FLIP transition with additive translate (position) and scale (size)
  • motion: 'system' reduced-motion support with the same keyframes on instant timing
  • Native timing: Omitted timing fields retain Web Animations API behavior
  • signal: Abort a handle from its parent lifecycle
  • dispose(): Idempotent cleanup with [Symbol.dispose]()

Deliberate Scope ​

Necromancer owns explicit WAAPI keyframes. It does not generate CSS keyframes, observe CSS transitions, watch mutations, simulate springs, interpolate SVG paths, or run a JavaScript tween loop. Use CSS for declarative style changes and choose a dedicated tool when those capabilities are required.

Documentation ​

See Also ​

  • Orbit: Position floating UI before animating its appearance.
  • Ore: Own Necromancer handles in a custom element's mount and disposal lifecycle.