Easing

Easings: a tween's curve, from its progress in time to its progress along the way, each a function of t from 0 to 1. Motion's named curves (easeIn, easeOut, backOut, anticipate…), which an ease gives as a string; the Penner set (easeOutCubic…); cubicBezier, steps, and spring, a spring as a curve. Any (t) => number is an easing too.

import * as Easing from "@wardic/core/Easing"

const ease = Easing.resolve("easeOut") // or [0.25, 0.1, 0.35, 1], or Easing.easeOutCubic
ease(0.5) // ≈ 0.69: past halfway at half the time

Interfaces

SpringOptions

A spring curve's options: its physics, stiffness, damping and mass, or its time, duration, bounce and visualDuration. They're a spring's options, so its other fields may come too: they're checked, but don't shape the curve.

Properties

bounce?

readonly bounce?: number;

How much a spring set by time bounces: 0 none, toward 1 a lot.

damping?

readonly damping?: number;

How damped it is: higher settles sooner, with less overshoot. Default 26.

duration?

readonly duration?: number;

A spring set by time: its curve runs to duration seconds, ending on 1.

mass?

readonly mass?: number;

The mass it moves: heavier is slower. Default 1.

stiffness?

readonly stiffness?: number;

How stiff it is: higher is snappier. Default 170.

visualDuration?

readonly visualDuration?: number;

A spring set by time that has done most of its move by visualDuration seconds: its curve runs to rest.

Type Aliases

Bezier

type Bezier = readonly [number, number, number, number];

A cubic bézier's control points, [x1, y1, x2, y2]: Motion's BezierDefinition.

Definition

type Definition = Name | Bezier | Easing;

An easing as an ease takes it, as Motion's: one of Motion's names, a cubic Bézier's four numbers, or a function.

Easing

type Easing = (t) => number;

An easing: a function from a tween's progress in time, 0 to 1, to its progress along the way. (t) => t * t is one.

Parameters

t

number

Returns

number

Name

type Name = 
  | "linear"
  | "easeIn"
  | "easeOut"
  | "easeInOut"
  | "circIn"
  | "circOut"
  | "circInOut"
  | "backIn"
  | "backOut"
  | "backInOut"
  | "anticipate";

Motion's names for its easings: what an ease string can be.

StepPosition

type StepPosition = "start" | "end";

Where each of steps' jumps happens: at the "start" of its interval, or its "end".

Variables

anticipate

const anticipate: Easing;

Motion's anticipate: backIn over the first half, then an exponential ease out. Per frame.

backIn

const backIn: Easing;

Motion's backIn: backOut reversed, back before it goes.

backInOut

const backInOut: Easing;

Motion's backInOut: backIn mirrored.

backOut

const backOut: Easing;

Motion's backOut: cubicBezier(0.33, 1.53, 0.69, 0.99), past its end and back. Not the Penner easeOutBack.

circIn

const circIn: Easing;

Motion's circIn: a quarter circle, slow then steep (the Penner easeInCirc's curve).

circInOut

const circInOut: Easing;

Motion's circInOut: circIn mirrored.

circOut

const circOut: Easing;

Motion's circOut: circIn reversed.

easeIn

const easeIn: Easing;

Motion's easeIn: cubicBezier(0.42, 0, 1, 1).

easeInBack

const easeInBack: Easing;

Penner's back curve: it draws back past its start, then goes.

easeInBounce

const easeInBounce: Easing;

Penner's bounce curve, reversed: it bounces at its start, then goes.

easeInCirc

const easeInCirc: Easing;

Penner's circular curve, a quarter circle; it starts slow and speeds up.

easeInCubic

const easeInCubic: Easing;

Penner's cubic curve, t³; it starts slow and speeds up.

easeInElastic

const easeInElastic: Easing;

Penner's elastic curve: it winds up, springing back and forth, then goes.

easeInExpo

const easeInExpo: Easing;

Penner's exponential curve: very sharp; it starts slow and speeds up.

easeInOut

const easeInOut: Easing;

Motion's easeInOut: cubicBezier(0.42, 0, 0.58, 1).

easeInOutBack

const easeInOutBack: Easing;

Penner's back curve: past its start, then past its end, then back.

easeInOutBounce

const easeInOutBounce: Easing;

Penner's bounce curve at both ends.

easeInOutCirc

const easeInOutCirc: Easing;

Penner's circular curve, a quarter circle; it slow at both ends and fast in the middle.

easeInOutCubic

const easeInOutCubic: Easing;

Penner's cubic curve, t³; it slow at both ends and fast in the middle.

easeInOutElastic

const easeInOutElastic: Easing;

Penner's elastic curve at both ends.

easeInOutExpo

const easeInOutExpo: Easing;

Penner's exponential curve: very sharp; it slow at both ends and fast in the middle.

easeInOutQuad

const easeInOutQuad: Easing;

Penner's quadratic curve, t²: a gentle one; it slow at both ends and fast in the middle.

easeInOutQuart

const easeInOutQuart: Easing;

Penner's quartic curve, t⁴: sharper; it slow at both ends and fast in the middle.

easeInOutQuint

const easeInOutQuint: Easing;

Penner's quintic curve, t⁵: the sharpest of the powers; it slow at both ends and fast in the middle.

easeInOutSine

const easeInOutSine: Easing;

Penner's sine curve: the softest; it slow at both ends and fast in the middle.

easeInQuad

const easeInQuad: Easing;

Penner's quadratic curve, t²: a gentle one; it starts slow and speeds up.

easeInQuart

const easeInQuart: Easing;

Penner's quartic curve, t⁴: sharper; it starts slow and speeds up.

easeInQuint

const easeInQuint: Easing;

Penner's quintic curve, t⁵: the sharpest of the powers; it starts slow and speeds up.

easeInSine

const easeInSine: Easing;

Penner's sine curve: the softest; it starts slow and speeds up.

easeOut

const easeOut: Easing;

Motion's easeOut: cubicBezier(0, 0, 0.58, 1). A tween's default.

easeOutBack

const easeOutBack: Easing;

Penner's back curve: it goes past its end, then comes back to it.

easeOutBounce

const easeOutBounce: Easing;

Penner's bounce curve: it lands and bounces to rest at its end, like a dropped ball.

easeOutCirc

const easeOutCirc: Easing;

Penner's circular curve, a quarter circle; it starts fast and slows to a stop.

easeOutCubic

const easeOutCubic: Easing;

Penner's cubic curve, t³; it starts fast and slows to a stop.

easeOutElastic

const easeOutElastic: Easing;

Penner's elastic curve: it springs past its end and back several times before it rests.

easeOutExpo

const easeOutExpo: Easing;

Penner's exponential curve: very sharp; it starts fast and slows to a stop.

easeOutQuad

const easeOutQuad: Easing;

Penner's quadratic curve, t²: a gentle one; it starts fast and slows to a stop.

easeOutQuart

const easeOutQuart: Easing;

Penner's quartic curve, t⁴: sharper; it starts fast and slows to a stop.

easeOutQuint

const easeOutQuint: Easing;

Penner's quintic curve, t⁵: the sharpest of the powers; it starts fast and slows to a stop.

easeOutSine

const easeOutSine: Easing;

Penner's sine curve: the softest; it starts fast and slows to a stop.

linear

const linear: Easing;

No easing: progress as time goes, at an even pace.

NAMES_LIST

const NAMES_LIST: ReadonlyArray<Name>;

Motion's names, for a decode to check an ease string against.

Functions

cubicBezier()

function cubicBezier(
   x1, 
   y1, 
   x2, 
   y2
): Easing;

A cubic Bézier easing through the control points (x1, y1) and (x2, y2). An ease of [x1, y1, x2, y2] is the same. x1 and x2 are from 0 to 1, as CSS's cubic-bezier() takes them; y1 and y2 may be any finite number, so the curve may overshoot. Anything else throws an OptionError naming the point, as an ease given in a transition does.

Parameters

x1

number

y1

number

x2

number

y2

number

Returns

Easing

Example

const standard = Easing.cubicBezier(0.4, 0, 0.2, 1)
const overshoot = Easing.cubicBezier(0.3, 1.6, 0.6, 1)

isBezier()

function isBezier(definition): definition is Bezier;

Whether definition is a bézier's points: an array whose first item is a number (Motion's isBezierDefinition).

Parameters

definition

unknown

Returns

definition is Bezier

nameOf()

function nameOf(easing): Option<string>;

The name an easing Wardic made was made with: a curve's own ("easeOutCubic"), or a factory's call with its arguments ("cubicBezier(0.4,0,0.2,1)", "steps(4,end)"). None for a function you wrote, which can't be told from another. A server names a mount animation's easing by it, so the server and the client agree.

Parameters

easing

Easing

Returns

Option<string>

resolve()

function resolve(definition): Easing;

The easing a definition gives: a name's curve, a Bézier through its points, or the function itself. Resolve once, where an animation is built, not each frame.

Parameters

definition

Definition

Returns

Easing

Example

const ease = Easing.resolve(options.ease ?? "easeOut")

reverse()

function reverse(easing): Easing;

An easing played backwards, which turns an ease-in into an ease-out: Motion's reverseEasing.

Parameters

easing

Easing

Returns

Easing

spring()

function spring(options?): Easing;

A spring as an easing: the spring's run from 0 to 1, until it rests, as a curve, so a tween of any duration moves as that spring would, its overshoot included. For whatever takes an easing; a value that should keep its velocity when its target changes runs on Machine.spring instead. A duration spring's curve ends at its duration, landing on 1. A value no spring can take, a stiffness at or below 0 say, throws an OptionError naming the field.

const ease = Easing.spring({ visualDuration: 0.5, bounce: 0.3 })

steps()

function steps(count, position?): Easing;

An easing in count jumps: each at the end of its interval (the default), or its start. For a value that should tick, not glide.

const tick = Easing.steps(12) // a clock hand's twelve jumps