Skip to content

UnknownPrinciple/oscillation

Folders and files

NameName
Last commit message
Last commit date

Latest commit

b88328a · Oct 21, 2024

History

70 Commits
Oct 17, 2024
Oct 21, 2024
Oct 17, 2024
Sep 25, 2024
Oct 21, 2024
Oct 21, 2024
Oct 17, 2024
Oct 18, 2024
Oct 17, 2024
Oct 21, 2024
Oct 17, 2024
Oct 18, 2024

Repository files navigation

Oscillation

npm install oscillation

Oscillation is a physics-based animation library for creating smooth, natural-looking animations.

import { motion, spring } from "oscillation";

// Animate a single value
motion(spring(0, 100), (value) => {
  console.log(value);
});

// Animate multiple properties
motion({ x: spring(0, 100), y: spring(0, 200) }, (state) => {
  console.log(state.x, state.y);
});

// Animate an array of values
motion([spring([0, 0, 0], [255, 128, 0]), spring(0, 360)], ([color, rotation]) => {
  console.log(color, rotation);
});

API

motion(defs, callback, options?)

Starts an animation and calls the callback with updated values on each frame. The motion function is overloaded to support different input types:

  1. Single motion object:
motion(spring(0, 100), (value) => {
  // value gets animated from 0 to 100
});
  1. Object with motion properties:
motion({ x: spring(0, 100), y: spring(-50, 50) }, ({ x, y }) => {
  // x and y animated simultaneously
});
  1. Array of motion objects:
motion([spring([0, 0, 0], [255, 128, 0]), spring(0, 360)], ([color, rotation]) => {
  // color and rotation animated simultaneously
});

Parameters:

  • defs: A single Motion object, an object with Motion values, or an array of Motion objects.
  • callback: A function called on each frame with the current state.
  • options: Optional object with an AbortSignal to stop the animation.

spring(source, destination, config?)

Creates a spring-based motion.

Parameters:

  • source: Initial value(s).
  • destination: Target value(s).
  • config: Optional spring configuration (damping, frequency, precision).

Supports various numeric types: number, Float64Array, Float32Array, Uint32Array, Int32Array, Uint16Array, Int16Array, Uint8Array, Int8Array, Array<number>.

Cancelling Animations

You can cancel ongoing animations using an AbortSignal:

let ctl = new AbortController();

motion(
  spring(0, 100),
  (value) => {
    console.log(value);
  },
  { signal: ctl.signal },
);

// To cancel the animation:
ctl.abort();

Support prefers-reduced-motion

If the user's system has reduced motion setting enabled, the animation path will be skipped and destination state going to be the only state rendered. To opt-out of this behavior and always animate the whole path, use ignoreReducedMotion flag:

motion(
  spring(0, 100),
  (value) => {
    console.log(value);
  },
  { ignoreReducedMotion: true },
);

Examples

Animating UI Elements

import { motion, spring } from "oscillation";

let button = document.querySelector("#myButton");

motion({ x: spring(0, 100), scale: spring(1, 1.2) }, (state) => {
  button.style.transform = `translateX(${state.x}px) scale(${state.scale})`;
});

Complex Color and Rotation Animation

import { motion, spring } from "oscillation";

let element = document.querySelector("#animatedElement");

motion([spring([0, 0, 0], [255, 128, 0]), spring(0, 360)], ([color, rotation]) => {
  let [r, g, b] = color;
  element.style.backgroundColor = `rgb(${r}, ${g}, ${b})`;
  element.style.transform = `rotate(${rotation}deg)`;
});

Prior Art

Oscillation project brings nothing significantly new to the scene and is based on the work of many engineers and researchers.

License

ISC License © Oleksii Raspopov