Module @okikio/animate

If you use the spring or spring-in easings it will also return the optimal duration as a key in the object it returns. If you set duration to a number, it will prioritize that duration over optimal duration given by the spring easings.

Read more about CustomEasing

e.g.

import { animate, ApplyCustomEasing } from "@okikio/animate";
animate({
     target: "div",

     ...ApplyCustomEasing({
       border: ["1px solid red", "3 dashed green", "2 solid black"],
       translateX: [0, 250],
       rotate: ["0turn", 1, 0, 0.5],
       "background-color": ["#616aff", "white"],

       // You don't need to enter any parameters, you can just use the default values
       easing: "spring",

       // You can change the size of Array for the CustomEasing function to generate
       numPoints: 200,

       // The number of decimal places to round, final values in the generated Array
       decimal: 5,

       // You can also set the duration from here.
       // When using spring animations, the duration you set here is not nesscary,
       // since by default springs will try to determine the most appropriate duration for the spring animation.
       // But the duration value here will override `spring` easings optimal duration value
       duration: 3000
     })
})

Custom Easing has 3 properties they are easing (all the easings from EasingFunctions are supported on top of custom easing functions like spring, bounce, etc...), numPoints (the size of the Array the Custom Easing function should create), and decimal (the number of decimal places of the values within said Array).

By default, Custom Easing support easing functions, in the form,

All Elastic easing's can be configured using theses parameters,

*-elastic(amplitude, period)

Each parameter comes with these defaults

All Spring easing's can be configured using theses parameters,

spring-*(mass, stiffness, damping, velocity)

Each parameter comes with these defaults

You can create your own custom cubic-bezier easing curves. Similar to css you type cubic-bezier(...) with 4 numbers representing the shape of the bezier curve, for example, cubic-bezier(0.47, 0, 0.745, 0.715) this is the bezier curve for in-sine.

Note: the easing property supports the original values and functions for easing as well, for example, steps(1), and etc... are supported.

Note: you can also use camelCase when defining easing functions, e.g. inOutCubic to represent in-out-cubic

Suggestion: if you decide to use CustomEasing on one CSS property, I suggest using CustomEasing or ApplyCustomEasing on the rest (this is no longer necessary, but for the sake of readability it's better to do)

e.g.

import { animate, CustomEasing, EaseOut, Quad } from "@okikio/animate";
animate({
  target: "div",

  // Notice how only, the first value in the Array uses the "px" unit
  border: CustomEasing(["1px solid red", "3 dashed green", "2 solid black"], {
      // This is a custom easing function
      easing: EaseOut(Quad)
  }),

  translateX: CustomEasing([0, 250], {
      easing: "linear",

      // You can change the size of Array for the CustomEasing function to generate
      numPoints: 200,

      // The number of decimal places to round, final values in the generated Array
      decimal: 5,
  }),

  // You can set the easing without an object
  // Also, if units are detected in the values Array,
  // the unit of the first value in the values Array are
  // applied to other values in the values Array, even if they
  // have prior units
  rotate: CustomEasing(["0turn", 1, 0, 0.5], "out"),
  "background-color": CustomEasing(["#616aff", "white"]),
      easing: "linear"
  }),

  // TIP... Use linear easing for the proper effect
  easing: "linear"
})

Based on https://github.com/w3c/csswg-drafts/issues/229#issuecomment-861415901

Note: the transform animation option will override all transform function properties

Note: the order of where/when you define transform function matters, for example, depending on the order you define translate, and rotate, you can create change the radius of the rotation

By default it will only give the optimal duration for spring or spring-in easing, this is to avoid infinite loops caused by the getEasingDuration() function.

Internally the SpringEasing uses CustomEasing, read more on it, to understand how the SpringEasing function works.

e.g.

import { animate, SpringEasing } from "@okikio/animate";

// `duration` is the optimal duration for the spring with the set parameters
let [translateX, duration] = SpringEasing([0, 250], "spring(5, 100, 10, 1)");
// or
// `duration` is 5000 here
let [translateX, duration] = SpringEasing([0, 250], {
     easing: "spring(5, 100, 10, 1)",
     numPoints: 50,
     duration: 5000,
     decimal: 3
});

animate({
     target: "div",
     translateX,
     duration
});

StaggerCustomEasing only supports array range values.

To use StaggerCustomEasing you need to do this,

import { animate, stagger, StaggerCustomEasing } from "@okikio/animate";
animate({
     target: ".div",
     
     translate: StaggerCustomEasing([0, 250], {
         // To set stagger options you need to do this
         stagger: { from "center" },
         
         // These options are for `CustomEasing`
         easing: "out-elastic",
         numPoints: 150
     }),
     delay: stagger(100),

     fillMode: "both",
     easing: "linear",
     duration: 5000
})

Check out demos on Codepen

There are more values of translateX, so the transform property created will look like this,

{
     transform: [
         "translateX(50px) scale(0.5)",
         "translateX(60px) scale(2)",
         "translateX(80px)",
         "translateX(90px)"
     ]
}

arrFill interpolates between all missing portions of transform functions, and helps create a uniform size transform property, e.g.

{
     transform: [
         "translateX(50px) scale(0.5)",
         "translateX(60px) scale(1)",
         "translateX(80px) scale(1.5)",
         "translateX(90px) scale(2)"
     ]
}

Note: it can also be used to determine the optimal duration of other types of easing function, but be careful of "in-" easing functions, because of the nature of the function it can sometimes create an infinite loop, I suggest only using getEasingDuration for spring, specifically "out-spring" and "spring"

Note: the red, green, and blue colors are rounded to intergers with no decimal places, while the alpha color gets rounded to a specific decimal place

Make sure to read interpolateNumber.

Make sure to read interpolateNumber, interpolateString, interpolateColor, and interpolateUsingIndex.

Basic interpolation works by scaling t from 0 - 1, to some start number and end number, in this case lets use 0 as our start number and 100 as our end number, so, basic interpolation would interpolate between 0 to 100.

If we use a t of 0.5, the interpolated value between 0 to 100, is 50. interpolateNumber takes it further, by allowing you to interpolate with more than 2 values, it allows for multiple values.

E.g. Given an Array of values [0, 100, 0], and a t of 0.5, the interpolated value would become 100.

Make sure to read interpolateNumber.

Note: 0 counts as valid

Staggering allows you to animate multiple elements with follow through and overlapping action.

It can be used like this,

import { animate, stagger } from "@okikio/animate";
animate({
     target: ".div",
     
     // `stagger` accepts range values but only an Array of 2 values are accepted,
     // the values can be either a "string" or a "number".

     // `stagger` distributes values evenly between two numbers,
     // so, given 5 elements, translate on the first element will be 0,
     // on the second element 50, on the third element 100, etc...

     // the equation is: 
     // (start value or first value in array range) + (((second value in the range) - (first value in the range)) / (total number of elements)) * (current index of element)
     // For an array of range `[-360, 360]`, 5 elements, and an undefined start value, you will get:
     //= -360 + ((360 - (-360)) / 5) * 0
     //= -360 + ((360 - (-360)) / 5) * 1
     //= -360 + ((360 - (-360)) / 5) * 2
     //= -360 + ((360 - (-360)) / 5) * 3
     //= -360 + ((360 - (-360)) / 5) * 4
     translate: stagger([0, 250]),

     // Single value staggers are also possible.
     // This increase delay by 100ms for each element.
     delay: stagger(100),

     fillMode: "both",
     easing: "linear",
     duration: 5000
});

stagger can also be used for grids. For grids you do this,

import { animate, stagger } from "@okikio/animate";
animate({
     target: ".div",
     
     // For grids you need to specify the size of the grid via stagger options
     // { grid: [number of columns, number of rows] }

     // and in this scenario we also need to specify the axis
     // { axis: "x" or "y" }
     translate: stagger([0, 30], { 
         grid: [14, 5], 
         axis: "x" 
     }),

     // Single value staggers are still possible.
     delay: stagger(100, { grid: [14, 5] }),

     fillMode: "both",
     easing: "linear",
     duration: 5000
});

the full list of staggering options are:

Check out demos on Codepen as well as animejs's stagger documentation

Because stagger returns an AnimationOption callback, it fundementally doesn't work with CustomEasing, so, you need to use StaggerCustomEasing to enable custom easing.

// { // "--translate0": [ // "0px", // "100px" // ], // "--translate1": [ // "60px", // "100px" // ], // "--translateX": [ // "60px", // "500px" // ], // "--translateY": [ // "60px", // "500px" // ] // }

Read more on underscorejs.org & lodash.com