html-trajectory

html-trajectory provides lightweight HTML animations to smoothly "fly" elements from their current position to a target element — for example, animating a product image flying into a shopping cart icon.
It’s ideal for parabolic movement, curved animations, and element-to-element transitions.

disclaimer: this project was happily vibe coded at it's "best" as an experiment. I used any LLM which did the job that moment.

But why?

I had been using a simple linear flyTo function for some time in a project, based on basic CSS transform and transition to move (and scale) elements.

One day I wondered:

Can two CSS animations with different easings be combined to create real curves?

The short answer:

• No, you cannot easily combine separate animations on the same element.
• Yes, you can create curves by wrapping the element inside a container and animating different properties separately.
• But — while simple curves are possible, there are limitations (still working on them :D)

So once I already had some basic functions working for linear and parabolic movements, I organized them into a small, reusable library.

Installation

npm install --save html-trajectory

or with yarn:

yarn add html-trajectory

Usage

import { flyTo } from "html-trajectory";

// Example: Fly a product image into the cart icon
flyTo('product-image', 'cart-icon');

Example HTML:

<img id="product-image" src="product.png">
<div id="cart-icon">🛒</div>

When calling flyTo('product-image', 'cart-icon'), the product image will fly straight into the cart icon.

API

flyTo(flyingId: string, targetId: string, options?: FlyOptions): void

Animates an element flying in a straight linear path to the target.

• flyingId — ID of the element to fly (the moving projectile).
• targetId — ID of the target element (the destination).
• options (optional) — A configuration object:
  • moveX — Whether to move horizontally (default is true).
  • moveY — Whether to move vertically (default is true).
  • duration — Animation duration in seconds (default is 1).
  • scale — Target scale factor at the end of animation (default is 1).
  • onTransitionEnd — Callback function that executes when the animation completes (default is an empty function).
  • removeOriginal — Whether to remove the original element (default is true).
  • resetTransformation — When true, resets the clone's transform and transform-origin after cloning (default is false).

cannonBall(flyingId: string, targetId: string, options?: FlyOptions): void

Animates an element flying along a parabolic arc without rotating the element itself — similar to a cannonball.

• flyingId — ID of the element to fly (the moving projectile).
• targetId — ID of the target element (the destination).
• options (optional) — A configuration object:
  • moveX — Whether to move horizontally (default is true).
  • moveY — Whether to move vertically (default is true).
  • duration — Animation duration in seconds (default is 1).
  • acceleration — Vertical acceleration in pixels/s² (default is 9.81). Higher values create a steeper arc.
  • fly3D — When true, disables acceleration to create a straight-line path instead of a parabolic arc (default is false).
  • scale — Target scale factor at the end of animation (default is 1).
  • onTransitionEnd — Callback function that executes when the animation completes (default is an empty function).
  • removeOriginal — Whether to remove the original element (default is true).
  • resetTransformation — When true, resets the clone's transform and transform-origin after cloning (default is false).

projectile(flyingId: string, targetId: string, options?: FlyOptions): void

Animates an element along a parabolic arc with rotation following the tangent of the trajectory — like a flying rocket or arrow.

• flyingId — ID of the element to fly (the moving projectile).
• targetId — ID of the target element (the destination).
• options (optional) — A configuration object:
  • moveX — Whether to move horizontally (default is true).
  • moveY — Whether to move vertically (default is true).
  • duration — Animation duration in seconds (default is 1).
  • acceleration — Vertical acceleration in pixels/s² (default is 9.81). Higher values create a steeper arc.
  • scale — Target scale factor at the end of animation (default is 1).
  • onTransitionEnd — Callback function that executes when the animation completes (default is an empty function).
  • removeOriginal — Whether to remove the original element (default is true).
  • resetTransformation — When true, resets the clone's transform and transform-origin after cloning (default is false).

Testing

The library uses Vitest for testing.

npm test

Coverage

To check test coverage, run:

npm run coverage

Coverage output will appear in the coverage/ folder.

Dev Container

Use the provided docker.sh script to start a dev container with the project mounted.
(Note: the script intentionally misses the executable bit.)

bash docker.sh

License

MIT