Skip to content
@staticbolt/core

Custom Ease Plugin

A staticbolt plugin that lets you use named easing functions in your CSS, JavaScript, and HTML with no runtime overhead. At build time, each call is replaced with its resolved CSS value: a cubic-bezier() for simple curves, or a linear() function for complex physics-based animations like springs, bounces, and elastics.

The plugin ships with a large set of predefined easing functions, and you can add your own.

Installation

The plugin ships as part of @staticbolt/core. You do not need to install anything else.

Usage

In your .staticbolt.ts:

import { defineConfig } from "@staticbolt/core";
import { customEasePlugin } from "@staticbolt/core/plugins";


export default defineConfig({
  plugins: [customEasePlugin()],
});

Replacement in CSS

Enabled by default. Write easing function calls with the --ease- prefix anywhere in a CSS declaration. The plugin replaces them with their CSS value at build time.

Simple curves resolve to cubic-bezier():

.element {
  transition-timing-function: --ease-out-cubic();
}


/* Output */
.element {
  transition-timing-function: cubic-bezier(0.33, 1, 0.68, 1);
}

Complex functions like springs, bounces, and elastics are sampled and resolved to a CSS linear() function:

.element {
  transition-timing-function: --ease-spring();
}


/* Output */
.element {
  transition-timing-function: linear(0, 0.018, ...);
}

Some easing functions accept arguments to control their behavior, for example spring(mass, stiffness, damping, velocity, duration), in-poly(n), or out-wobble(bounciness).

Predefined easing functions

These easing functions are available out of the box.

In

in-sine, in-quad, in-cubic, in-quart, in-quint, in-expo, in-circ, in-back(c1?), in-bounce(), in-elastic(), in-poly(n), in-wobble(bounciness?)

Out

out-sine, out-quad, out-cubic, out-quart, out-quint, out-expo, out-circ, out-back(c1?), out-bounce(), out-elastic(), out-poly(n), out-wobble(bounciness?)

In-Out

in-out-sine, in-out-quad, in-out-cubic, in-out-quart, in-out-quint, in-out-expo, in-out-circ, in-out-back(c1?), in-out-bounce(), in-out-elastic(), in-out-poly(n), in-out-wobble(bounciness?)

Special

spring(mass?, stiffness?, damping?, velocity?, duration?), custom(svgPath)

The custom function takes an SVG path string and converts it into an easing function. You can draw the curve with any vector tool and use it directly.

Replacement in JavaScript

Disabled by default. Enable it with replaceInJS: true. The plugin looks for calls in the form cssLinear.<easeName>() and replaces them with the resolved CSS string at build time.

Write easing names in camelCase in JavaScript. The plugin maps them to their kebab-case counterparts.

The result can be used with the Web Animations API.

const ease = cssLinear.outBounce();
// → "linear(0, 0.004, 0.016, ...)"


const curve = cssLinear.inOutCubic();
// → "cubic-bezier(0.65, 0, 0.35, 1)"

Replacement in inline style attributes

Disabled by default. Enable it with replaceInHtmlStyleAttribute: true. Works the same as CSS replacement but applies to style attributes in HTML elements.

<div style="transition-timing-function: --ease-out-spring(1, 80, 12)"></div>


<!-- Output -->
<div style="transition-timing-function: linear(0, 0.018, ...)"></div>

Custom easing functions

Use the customEase option to define your own easing functions alongside the predefined set. A custom easing can be a CSS string or a JavaScript function. When you give it a function, the plugin samples it and converts the result to a CSS linear() function.

customEasePlugin({
  customEase: {
    // Resolves to cubic-bezier()
    "in-circ": "cubic-bezier(0.55, 0, 1, 0.45)",


    // Resolved to linear() using the configured number of samples
    "out-poly": (n: number) => (t: number) => 1 - Math.pow(1 - t, n),
  },
});
.element {
  transition-timing-function: --ease-out-poly(4);
}

Plugin Options

replaceInCSS

  • Type: boolean
  • Default: true

Enables replacement of easing functions in CSS declarations.

cssFunctionPrefix

  • Type: string
  • Default: "--ease-"

The prefix that marks an easing function call in CSS and inline styles.

replaceInJS

  • Type: boolean
  • Default: false

Enables replacement of easing function calls in JavaScript.

jsFunctionName

  • Type: string
  • Default: "cssLinear"

The namespace for easing calls in JavaScript. The plugin looks for calls in the form <jsFunctionName>.<easeName>().

replaceInHtmlStyleAttribute

  • Type: boolean
  • Default: false

Enables replacement of easing functions inside inline style attributes in HTML.

customEase

  • Type: Record<string, string | ((...args: unknown[]) => EaseFunction)>
  • Default: {}

Additional easing definitions merged with the predefined set.

samples

  • Type: number
  • Default: 50

How many samples are taken when a JavaScript easing function is converted to a CSS linear() function. A higher value gives a smoother curve at the cost of a larger output string.