A small utility function for handling multi-step animations. Can handle everything from the most simple use cases to much more complex ones with an extremely robust hook system. All without sacrificing speed.
Currently built for use with HTMLElements, but can also just be used purely for it's hooks, making it easy to use with libraries like React, Redux, Vue, and so on.
To install with npm
npm install simply-animate --save
To install with yarn
yarn add simply-animate
And pnpm
pnpm add simply-animate
Getting started with the animationSeries
function is fairly simple. All you have to do is call the function, and pass step objects to it.
The easiest way to use this function is to pass an HTMLElement to it, define durations and step names for each step, and use CSS to apply whatever animations, transitions, or styles needed for each step.
import { animationSeries } from 'simply-animate';
// Basic Example
animationSeries({
element: document.getElementById('exampleThingToAnimate'),
seriesClassName: 'series-example',
steps: [
{
name: 'action-1',
duration: 300
},
{
name: 'action-2',
duration: 400
}
]
});
<!-- HTML durring step 1 -->
<div class="animation__series-example__action-1 animation__series-example__in-progress">
<!-- Content!! -->
</div>
<!-- HTML durring step 2 -->
<div class="animation__series-example__action-2 animation__series-example__in-progress">
<!-- Content!! -->
</div>
In this example, a few classes will be added to the element passed. An "in progress" class, as well as step classes. The step classes, however, are added and removed as the series executes each step.
The "in progress" class for this example:
.animation__series-example__in-progress
Step 1's class:
.animation__series-example__action-1
Step 2's class:
.animation__series-example__action-2
When the series is finished, all remaining classes added will be removed.
This package is written in typescript and should be compatible out-of-the-box.
However, to get access to the types and interfaces included in this package directly: (just in case. It's an edge case, but who knows?)
import { Types } from 'simply-animate';
// Or if you have to rename
import { Types as MyNewTypes } from 'simply-animate';
The animationSeries
function takes an object as its argument.
Props | Type | Required | Description |
---|---|---|---|
element |
HTMLElement | HTMLElement object that the animation classes will be applied to. | |
namespaceClass |
string | The first namespace in the CSS class name. This is meant to allow for replacing the globally used namespace at a function by function level. | |
seriesClassName |
string | ✅ | The function level namespace for the animation. |
hooks |
object | See function Hooks for more info. | |
steps |
array | ✅ | An array of Step objects. At least one must be passed. |
Props | Type | Required | Description |
---|---|---|---|
name |
string | ✅ | Name of the step to be used in the CSS class name. |
duration |
number | ✅ | duration of the step in milliseconds. |
hooks |
object | Hooks specific to the animation step. See Step Hooks below. |
These hooks apply to the entire series. Use Step Hooks to hook into individual steps in the animation series.
Props | Type | Required | Description |
---|---|---|---|
before |
function | Fires before the first animation frame is requested. | |
beforeEachStep |
function | Fires at the beginning of each step, before the css classes are updated. | |
duringEachStep |
function | Fires after css classes are updated for each step. | |
onEachFrame |
function | Fires before every frame. | |
afterEachFrame |
function | Fires after every frame, but before afterEachStep hook is fired when the hooks share a frame. |
|
afterEachStep |
function | Fires at the end of each step, at the same time the step index is being incremented. | |
after |
function | Fires at the end of all the steps, in place of requesting another animation frame. |
Props | Type | Required | Description |
---|---|---|---|
before |
function | Fires at the beginning of the step, before classes are updated, but after beforeEachFrame when the hooks share a frame. |
|
during |
function | Fires after classes have been updated, but after the duringEachStep series hook. |
|
beforeEachFrame |
function | Fires at the beginning of each frame but after the beforeEachFrame series hook. |
|
afterEachFrame |
function | Fires at the end of each frame, after all step hooks that share the frame. | |
after |
function | Fires at the end of each step, but after afterEachStep series hook. |
All hook functions are passed an object as a single param.
Props | Type | Description |
---|---|---|
element |
HTMLElement | Element passed to the AnimationSeries function. This will only be present if an element was passed to the animationSeries function. |
progress |
object | Object containing different progresses of the animation. |
progress.series |
number | Progress of entire animation series represented as a number between 0 and 1. |
progress.step |
number | Progress of the active step represented as a number between 0 and 1. |
This is mostly untested as of now, so please use at your own risk.
The String defaults used in the css class name generation can be overwritten with the updateConfig
function.
Warning: This is NOT a function by function basis, and will update values that all uses of this function will use. There may be a future update where each function can be individually configured if there is enough need for it.
The current config object has two keys.
Key | Type | Description |
---|---|---|
namespace |
string | The namespace that will be used in the animation css classes added to the passed HTMLElement |
inProgress |
string | The terminology that will be used when the css classes are added to allow targeting based on the animation being in progress at all |
import { updateConfig } from 'simply-animate';
updateConfig({
namespace: 'new-namespace-name',
inProgress: 'is-active'
});
animationSeries({
element: document.getElementById('exampleThingToAnimate'),
seriesClassName: 'series-example',
steps: [
{
name: 'action-1',
duration: 300
},
{
name: 'action-2',
duration: 400
}
]
});
In the example above, the following classes would be generated:
The "in progress" class for this example:
.new-namespace-name__series-example__is-active
Step 1's class:
.new-namespace-name__series-example__action-1
Step 2's class:
.new-namespace-name__series-example__action-2