talski / brease.js

brease.js

All-in-one adjustable easing functions library

• Penner's easing functions
• Custom cubic Bézier curve functions
• Custom elastic curve functions
• Custom step/staircase functions
• Custom back curve functions

• Adjustable input and output range
• In, out, in-out and out-in variants
• Supports IntelliSense and TypeScript
• No dependencies, no framework cruft

Getting started

Installation

Via npm:

$ npm i brease.js

Usage

ESM:

import { Easing, Penner, Bezier, Steps, Elastic, Back } from "brease.js";

CJS:

const { Easing, Penner, Bezier, Steps, Elastic, Back } = require("brease.js");

Example

A simple eased animation using a Penner function to translate a circle on the x-axis from -100px to 100px during 1000ms.

import { Penner } from "brease.js";

let duration = 1000,
start = performance.now(),
element = document.getElementById("circle"),
easing = new Penner("outQuint", -100, 100, 0, duration);

let tick = () => {
  let time = performance.now();
  element.style.transform = `translateX(${easing.at(time-start)}px)`;
  if(time-start < duration) requestAnimationFrame(tick);
};

tick();

API

Easing

Constructor

new Easing(easing?, o1?, o2?, t1?, t2?)

easing?: string | ((t: number) => number)

The easing function to use. Can be a custom function or the name of a preset. A list of all supported presets can be found below. Default is "linear".

o1?: number

Start of the output range, e.g. beginning value. Default is 0.

o1?: number

End of the output range, e.g. ending value. Indicates the easing's change in value in combination with o1. Default is 1.

t1?: number

Start of the input range, e.g. start time. Default is 0.

t2?: number

End of the input range, e.g. end time. Indicates the easing's duration in combination with t1. Default is 1.

Properties

fn: (t: number) => number

Returns the easing function adjusted to the easing's input and output range.

time: Time

Manages the easing's input range. Has the following sub-properties:

• start: number Sets/gets the start.
• end: number Sets/gets the end.
• duration: number Sets/gets the duration.
• range: [start: number, end: number] Sets/gets the start and end using an array.

output: Ouput

Manages the easing's output range. Has the following sub-properties:

• start: number Sets/gets the start.
• end: number Sets/gets the end.
• delta: number Sets/gets the change in value.
• range: [start: number, end: number] Sets/gets the start and end using an array.

Methods

at(t: number): number

Returns the output value for the specified time.

keyframes(n: number): number[]

Returns an array of output values by splitting the easing into n equal parts.

inverse()

Inverts the easing.

clone()

Returns a new instance with the same easing function and input and output range.

Presets

• "linear"
• "ease", "easeIn", "easeOut" and "easeInOut"
• "stepStart" and "stepEnd"
• All Penner functions, prefixed with "ease" (e.g. "outQuint" → "easeOutQuint")

Example

let easing = new Easing("easeOutQuint", 0, 100, -200, 200);
// → input ranges from 0 to 100 
// → output ranges from -200 to 200 

easing.output.start -= 200;
// → output ranges from -400 to 200 

easing.time.range = [0, 1];
// → output ranges from 0 to 1 

easing.output.delta = 400;
// → output ranges from -400 to 0 

easing.invert();
// → output ranges from 0 to -400 

Penner

This class can be used to quickly create an easing using one of Robert Penner's functions. All functions work identically to Penner's. Extends Easing.

Constructor

new Penner(name, ...args?)

name: string

Name of Penner function. A list of all supported names can be found below.

...args?

The same arguments as Easing.

Functions

Each of Penner's functions has an in, out, in-out and out-in variant. If you want to learn more about these functions, visit easings.net ↗.

	In	Out	In-Out	Out-In
Quad	inQuad	outQuad	inOutQuad	outInQuad
Circ	inCubic	outCubic	inOutCubic	outInCubic
Quart	inQuart	outQuart	inOutQuart	outInQuart
Quint	inQuint	outQuint	inOutQuint	outInQuint
Expo	inExpo	outExpo	inOutExpo	outInExpo
Sine	inSine	outSine	inOutSine	outInSine
Circ	inCirc	outCirc	inOutCirc	outInCirc
Back	inBack	outBack	inOutBack	outInBack
Elastic	inElastic	outElastic	inOutElastic	outInElastic

Bezier

This class can be used to create a custom cubic Bézier curve easing. You can use a Bézier curve generator ↗ to visualise the curve and generate the corresponding parameters. Extends Easing.

Constructor

new Bezier(x1, y1, x2, y2, ...args?)

x1: number

X coordinate of P1. Must be between 0 and 1.

y1: number

X coordinate of P1.

x2: number

X coordinate of P2. Must be between 0 and 1.

y2: number

Y coordinate of P2.

...args?

The same arguments as Easing.

Steps

This class can be used to define a step function. Divides the output range into equidistant steps. Visit the MDN docs ↗ for more information. Extends Easing.

Constructor

new Steps(number, direction?, ...args?)

number: number

The number of equidistant steps that make up the function. Must be a strictly positive integer.

direction?: string

Indicates if the function is left- or right-continuous. Must be one of:

• "start": Denotes a left-continuous function. The first step happens when the interpolation begins.
• "end": Denotes a right-continuous function. The last step happens when the interpolation ends.
• "both": Denotes a right and left continuous function. Includes a pause at the start and end of the interpolation.
• "none": There is no jump on either end. The value is held at the start and end of the interpolation.

The default is "end"

...args?

The same arguments as Easing.

Elastic

This class can be used to define a custom elastic curve easing. Extends Easing.

Constructor

new Elastic(amplitude?, period?, direction?, ...args?)

amplitude?: number

Amplitude, i.e. overshoot of the curve. Must be at least 1. Default is 1.

period?: number

Period, i.e. how many times the curve goes back and forth. The smaller the number, the more times the curve goes back and forth. Must be larger than 0. Default is 0.3.

direcrion?: string

Direction of the easing function. Must be one of "in", "out", "inOut" and "outIn". Default is "in".

...args?

The same arguments as Easing.

Back

This class can be used to define a custom back curve easing. Extends Easing.

Constructor

new Back(overshoot?, direction?, ...args?)

overshoot?: number

Overshoot of the curve. Must be at least 1. Default is 1.5.

direcrion?: string

Direction of the easing function. Must be one of "in", "out", "inOut" and "outIn". Default is "in".

...args?

The same arguments as Easing.