JSON Animation Schema

AnimX features a powerful JSON-first schema parser (AnimX.fromJSON) that allows you to define complex timelines, tweens, keyframes, and staggers entirely through JSON objects.

This is extremely useful for:

• Saving and loading animations from a database.
• Building low-code/no-code animation editors.
• Keeping your JavaScript controllers clean by defining animations in external .json files.

Basic Usage

You can pass a raw JavaScript object or a JSON string into AnimX.fromJSON(doc). It parses the document and returns a live Timeline object that you can immediately play().

import AnimX from 'animx';

const schema = {
  version: "1.0",
  tweens: [
    {
      target: ".box",
      duration: 1,
      props: { x: 100, opacity: 0.5 },
      ease: "power2.out"
    }
  ]
};

const tl = AnimX.fromJSON(schema);
tl.play();

Schema Structure

An AnimX JSON document must have at least one of the following root properties:

• tweens: An array of individual tween objects.
• timeline: A complex timeline object with nested tweens, labels, and timelines.

Top-Level Properties

• version (string): "1.0"
• defaults (object): Global defaults applied to all tweens in the document (e.g. duration, ease, repeat).
• tweens (array): A flat array of tweens to run concurrently.
• timeline (object): A root timeline definition.

---

Tween Definitions

A tween object within the schema supports the following properties:

• target (string | array): CSS selector(s) for the target elements. (Required)
• type (string): The type of tween. Options: "animate", "animateFrom", "sequence", "apply". Default is "animate".
• duration (number): Duration in seconds.
• delay (number): Delay in seconds.
• ease (string): The easing function (e.g., "power3.inOut", "bounce.out", "linear").
• position (string | number): Where to place the tween in a timeline (e.g., "-=0.5", "myLabel", 1.5).
• props (object): The CSS properties to animate to/from.
• fromProps (object): Required if type is "sequence". The starting properties.
• stagger (number | object): A stagger amount in seconds, or a complex stagger config object (amount, each, grid, ease).
• keyframes (array): An array of keyframe objects for segmented animations (see below).

Callbacks

You can reference JavaScript callbacks by name in your JSON. These must be registered beforehand via AnimX.registerCallback(name, fn).

Supported callbacks: onStart, onUpdate, onComplete, onRepeat, onReverseComplete.

AnimX.registerCallback("myCompleteFunc", () => console.log("Done!"));

const schema = {
  tweens: [{ target: ".box", props: { x: 100 }, onComplete: "myCompleteFunc" }]
};

---

Timelines

If you want sequential or nested animations, define a timeline object.

{
  "timeline": {
    "repeat": -1,
    "yoyo": true,
    "labels": {
      "start": 0,
      "middle": 1.5
    },
    "tweens": [
      { "target": ".box1", "duration": 1, "props": { "x": 100 } },
      { "target": ".box2", "duration": 1, "props": { "y": 100 }, "position": "-=0.5" },
      { "target": ".box3", "duration": 1, "props": { "scale": 2 }, "position": "middle" }
    ]
  }
}

---

Keyframes

The keyframes property is a special feature of the JSON schema. It allows you to build a single tween that animates through multiple waypoints.

Each keyframe object requires:

• at (number | string): The relative position in the total duration. Can be a decimal (0.5) or a percentage ("50%").
• props (object): The properties to animate to.
• ease (string): Optional. The easing curve between the previous keyframe and this one.

{
  "tweens": [
    {
      "target": ".box",
      "duration": 4,
      "keyframes": [
        { "at": "0%", "props": { "x": 0, "opacity": 0 } },
        { "at": "20%", "props": { "x": 100, "opacity": 1 }, "ease": "power2.out" },
        { "at": "80%", "props": { "x": 300, "opacity": 1 }, "ease": "linear" },
        { "at": "100%", "props": { "x": 400, "opacity": 0 }, "ease": "power2.in" }
      ]
    }
  ]
}

Behind the scenes, the Schema Parser calculates the relative segment durations and seamlessly links them together into a unified sequence.