phena

🔮 Petit tweening engine based on requestAnimationFrame

The name of the library comes from the phenakistiscope discs, one of the first motion artifacts used for entertainment.

Install

Add it to your application using a package manager.

# npm
npm i phena --save

# yarn
yarn add phena

You can also drop it in the browser using a script with https://unpkg.com/phena as source.

Tween class

To start tweening a value import the Tween class first and pass the options.

import { Tween } from 'phena'

new Tween({ from: 1, to: 10, duration: 2000 })

This will iterate values from 1 to 10 in 2 seconds.

To react to this iteration define an onUpdate method.

import { Tween } from 'phena'

function onUpdate(value) { console.log(value) }

new Tween({ from: 1, to: 10, duration: 2000, onUpdate })

All actions are queued using requestAnimationFrame which makes this tweening engine perfect for actions that will trigger paint jobs or layout calculations in the browser.

start

If you passed paused: true to options, start will allow you to kick off the tweening.

import { Tween } from 'phena'

const tween = new Tween({ from: 1, to: 10, duration: 2000, paused: false })

tween.start()

cancel

Stop the tweening at any time.

import { Tween } from 'phena'

const tween = new Tween({ from: 1, to: 10, duration: 2000 })

tween.cancel()

The library doesn't support pause and resume actions yet.

Available options

List of properties you can pass to options object:

• from required, initial numeric value
• to required, final numberic value
• duration required, tweening time in milliseconds
• delay, delay time in milliseconds
• onUpdate, function to execute on each value update
• onComplete, function to execute when tweening has finished
• paused, don't start tweening on instantiation, false by default
• ease, function to alter the rate of change in the value pass to onUpdate

Contributing

To contribute Node.js and yarn are required.

Before commit make sure to follow conventional commits specification and check all tests pass by running yarn test.

Disclaimer

phena works similar to basic time based tweening utility, but internally it relies on enqueueing callbacks in the paint thread so it's ideal for scheduling animation jobs.

This package is not an animation library and has no intentions to become one, so it won't expose a richful API like other tools out there. For now, it just provides the minimum set of options to iterate over value updates, focusing on animation of DOM elements.