Tweezer.js
A small, dependency-free, ES6 library for smooth animations. Demo.
Tweezer.js is the last tweening library you'll ever need. It provides the building blocks for any animation, allowing you to construct beautiful animations simply and without the need of requiring lots of other dependencies like smoothScroll, countUp.js, and GSAP.
Install
Tweezer was developed with a modern JavaScript workflow in mind. To use it, it's recommended you have a build system in place that can transpile ES6, and bundle modules. For a minimal boilerplate that fulfills those requirements, check out outset or the gh-pages branch of this repo.
To install, run
$ npm install tweezer.js --save
Use
Two parameters are required to start Tweezer, a start
and an end
value, the rest is optional. Tweezer works by emitting tweened values from start
to end
via the tick
event. It is up to you on how to use these values.
Below are all of the default configuration options. Note: all methods can be chained.
import Tweezer from 'tweezer.js'
new Tweezer({
start: 0,
end: 0,
duration: 1000,
easing: (t, b, c, d) => {
if ((t/=d/2) < 1) return c/2*t*t + b
return -c/2 * ((--t)*(t-2) - 1) + b
}
})
.on('tick', value => {
// do something with value
})
.on('done', ()=> {
// all done
})
.stop() // this stops the tweening
.begin() // this fires the tweening
Examples and Use Cases
Add a Tweened Count Up Button
let countUpText = document.querySelector('#count-up')
let countUpButton = document.querySelector('#count-up-button')
countUpButton.onclick = ()=> {
new Tweezer({
start: 0,
end: 123456
})
.on('tick', v=> countUpText.textContent = v)
.begin()
}
Smooth Scroll to an Element
let button = document.querySelector('#jump-button')
let elementYouWantToScrollTo = document.querySelector('#element')
button.onclick = ()=> {
new Tweezer({
start: window.scrollY,
end: elementYouWantToScrollTo.getBoundingClientRect().top + window.scrollY
})
.on('tick', v => window.scrollTo(0, v))
.begin()
}
start
is the current scroll position. end
is set to the top of the element plus the current scroll position,
which will yield the document Y position of the element.
Move an Element Across the Screen
let mover = document.querySelector('#move-across-screen')
let moverButton = document.querySelector('#move-across-screen-button')
moverButton.onclick = ()=> {
new Tweezer({
start: mover.getBoundingClientRect().left,
end: window.innerWidth - mover.getBoundingClientRect().width
})
.on('tick', v=> {
mover.style.transform = `translate3d(${v}px, 0, 0)`
})
.begin()
}
Configuration
Tweezer only has a couple of options, but these options can be very powerful. Again, only required options to run tweezer are start
and end
. And all methods are chainable.
Start and End
new Tweezer({
start: 0,
end: 9000
})
These are integers that define a start of tween and an end of tween. start
can be greater than or less than end
for tweening up and down.
Easings
new Tweezer({
easing: (t, b, c, d) => {
if ((t/=d/2) < 1) return c/2*t*t + b
return -c/2 * ((--t)*(t-2) - 1) + b
}
})
The default easing is easeInOut
. If you'd like to add your own easing, implement a function that takes in four parameters: t, b, c, d
and returns a single integer. For examples of easings, checkout ez.js. Parameters explained below.
t: current time,
b: beginning value,
c: change in value,
d: duration
Tweeners
By setting the start
and end
properties, Tweezer uses a default tweener that simply tweens directly from start
to end
. This behavior can be overridden by explicitly specifying a tweener
in the config instead. There is only one alternate tweener currently, called MultiTweener
. This tweener allows you to tween several different values simultaneously and in sync.
import Tweezer from 'tweezer.js'
import { MultiTweener } from 'tweezer.js/dist/multi-tweener'
new Tweezer({
tweener: new MultiTweener({
starts: [0, 500, -100],
ends: [50, 400, 0]
})
})
.on('tick', ([v1, v2, v3]) => {
el1.style.top = v1;
el2.style.top = v2;
el3.style.top = v3;
})
.begin()
Using the Emitter
To handle events, use the .on(handlerName, callback)
method.
Tick Event
This is where you'll do the bulk of animation by handling the values return by Tweezer. With these values you can do anything like transforming and manipulating DOM elements.It will fire every 16ms via requestAnimationFrame
.
new Tweezer({
start: 0,
end: 9000
})
.on('tick', v => el.style.transform = `transform3d(v, 0, 0)`)
End Event
This event fires when tweening has reached the end
value. All tweening is complete when this event is fired.
new Tweezer({
start: 0,
end: 9000
})
.on('done', v => alert('All Done!'))
Begin the Tween
To start tweening, just run the begin()
method.
Stopping the Tween
If you'd like to stop tweening for whatever reason, call the stop
method. This will reset everything and cancel the animation frame from firing.
Browser Support
Tweezer.js depends on the following browser APIs:
Consequently, it supports the following natively:
- Chrome 24+
- Firefox 23+
- Safari 6.1+
- Opera 15+
- IE 10+
- iOS Safari 7.1+
- Android Browser 4.4+
To add support for older browsers, consider including polyfills/shims for the APIs listed above. There are no plans to include any in the library, in the interest of file size.
What is Tweening?
A tween is when you animate something with some kind of easing. Any time you want to animate something smoothly with JS, you need to tween it. For example, you can tween count-up-buttons, smooth scrolling, and the height of elements. Instead of requiring libraries for all of these same functions, you can use this library as a utility to build out these examples.
License
MIT. © 2017 Jackson Geller