# crossani

> A silky smooth declarative animation library for the web.

Latest version **1.3.3** (published 2022-11-02) · MIT license · 0 weekly downloads

## Install

```sh
npm install crossani
pnpm add crossani
yarn add crossani
bun add crossani
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.3.3 |
| Published | 2022-11-02 |
| First published | 2022-05-05 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 44.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Cain Atkinson |
| Maintainers | yellowsink, lexisother |

## Links

- npm: https://www.npmjs.com/package/crossani
- npm.io page: https://npm.io/package/crossani

## Recent versions

- 1.3.3 (latest) — 2022-11-02
- 1.3.2 — 2022-06-21
- 1.3.1 — 2022-06-16
- 1.3.0 — 2022-06-16
- 1.2.1 — 2022-06-13
- 1.2.0 — 2022-06-05
- 1.1.1 — 2022-05-11
- 1.1.0 — 2022-05-11
- 1.0.1 — 2022-05-05
- 1.0.0 — 2022-05-05

## README

# CrossAni

A silky smooth declarative animations lib for the web.

## Why CrossAni?

### Browser-Native Performance

A traditional animation library works by updating a property of an element repeatedly with JavaScript.

This is required for things like SVG elements, and is also much much easier for more complex animations such as springs.

However: this can have performance repurcussions.

CrossAni uses CSS transitions to fix this problem, using the browser's built in animating tools.

**CrossAni effectively guarantees 60fps animations every time**, or whatever refresh rate you run at.

The main other way to achieve this is the Web Animations API (WAAPI) like Motion One does.

### Size Matters

We live in an era of shaving milliseconds off load times, and a good chunk of this is JS bundle size.

CrossAni is _TINY_. As I write this it's 2.81KB raw or 1.25KB gzipped.
This is much smaller than the major animation libraries available (see comparisons further down).

## How does it behave?

Each element has an independent queue of pending animations.

When you run an animation it will be queued to run, or if the element is stationary, will animate immediately.

The queue will automatically run one-after-the-other until all animations are complete.

Any animations with `cutOff: true` set will interrupt the current animation,
cause all animations on the queue to finish instantly (we don't even transition them, just apply their changes!),
and then run itself as usual from the final styles applied by all preceeding animations.

CrossAni will only replace styles specified at each state.
If you do not want a state to allow leaving residue of the previous states, set `reset: true`.

All styles present on the element before the first animation ran will be respected,
and will be returned to those value after a reset.

Any _inline_ styles set after an animation has run on that element will readily be overwritten by CrossAni,
so be aware of that.

You can deal with this by using the `element.caSet(prop, value)` function.
This will let you set a value on the inline styles without conflicting with CrossAni,
however do note that styles set this way are removed when `removeCrossAni()` is called.

You can prevent overwrites by calling `element.removeCrossAni()` after an animation.
This will remove any residual styles from transitions, but leave your `transitions` prop intact.

You can then modify the styles, and call `doTransition` as usual, re-initing that elem's animations

## How do I use it?

### (1) Assign some states to your element

Any element that should be animated can have a `transitions` property with a key-value record of strings to transition
objects.

You may also pass transition objects directly to doTransition,
which is helpful for programmatically generated animations for example.

A transition object contains the following things:

- `ms`: the time it should take to finish transitioning to that state
- `easing`: An easing function to use, all exported on the `EASE` object.
- `state`: An object containing the CSS values to set on the element this state.
- `cutOff`: see behaviour above
- `reset`: see behaviour above
- `detached`: if true, this transition is completely independent of the global queue and runs instantly.

Transition objects allow all properties to be undefined, and will provide useful defaults:

```js
({
	state: {},
	ms: 100, // falls through from past transition, this value is for the first transition
	easing: EASE.ease, // see above comment
	cutOff: false,
	reset: false,
	detached: false
})
```

An example setup would be as follows:

```js
const box = document.getElementById("box");

box.transitions = {
	default: {
		ms: 500,
		easing: EASE.inOut,
		reset: true,
		cutOff: true,
	},

	hover: {
		state: {transform: "scale(1.1)"},
		ms: 250
	},
};
```

### (2) Get animating!

You may call `doTransition` on an element to cause it to animate to a named state.

The first time you do this, CrossAni will take a note of inline styles, as described before.

For, example, to continue with our box example:

```js
// ignore that this example could better be done
// with a :hover selector, this is just for the demo
box.onmouseover = () => box.doTransition("hover");
box.onmouseleave = () => box.doTransition("default");
```

### (3) Build up complex transitions with ease

Promises make complexity into simplicity

```js
async function introAnimation() {
	box.doTransition("moveright");
	box.doTransition("slowgrow");
	await box.doTransition("fadetextout");
	box.innerText = "the text is now different";
	box.doTransition("fadetextin");
	await box.doTransition("makemassive");
}
```

## What's the most performant?

`opacity`, `transform`, `filter`, as these are things that can be done in the compositor stage.

`background-color` and `clip-path` may be accelerated in Chrome too, but ensure to test in all browsers for optimum
speed.

Non `transform` _movements_ are slower as, although the browser is running the animation,
repaints and often reflows are necessary, which are expensive.

To answer the more important question, what's the least performant, anything that could affect layout,
such as `margin`, `padding`, `width`, `height`, `font`, flex attributes, etc.

## How does CrossAni stack up?

Most benefits Motion One list also apply here:

- super small
- super smooth
- not affected by JS execution freezing
- high accuracy interpolation from the browser

However, CrossAni does not support some SVG attributes such as `d`.

### Bundle size

All packages were ran through [bundlejs](https://bundlejs.com) with esm.sh as the cdn.

| Pkg         | Raw     | Gzip    | Brotli  | Bar (br)   |
|-------------|---------|---------|---------|------------|
| crossani    | 2.8kb   | 1.25kb  | 1.18kb  | ▌          |
| ca + spring | 4.05kb  | 1.88kb  | 1.8kb   | ▊          |
| motion      | 15.07kb | 6.34kb  | 6.17kb  | ██▌        |
| animejs     | 17.59kb | 7.19kb  | 6.99kb  | ███        |
| gsap        | 61.97kb | 24.45kb | 23.86kb | ██████████ |

### Features

|              |            Feature | CrossAni  |  Motion  | AnimeJS | Greensock |
|--------------|-------------------:|:---------:|:--------:|:-------:|:---------:|
| **Values**   |    CSS `transform` |     ✅     |    ✅     |    ❌    |     ✅     |
|              |      Named colours |     ✅     |    ✅     |    ❌    |  Partial  |
|              |   Colour type conv |     ✅     |    ✅     |    ✅    |     ✅     |
|              |   To/from CSS vars |     ✅     |    ✅     |    ❌    |     ❌     |
|              |  To/from CSS funcs |     ✅     |    ✅     |    ❌    |     ❌     |
|              |   Animate CSS vars |     ❌     |    ✅     |    ❌    |     ❌     |
|              |   Simple keyframes |   ❌ WIP   |    ✅     |    ✅    |     ❌     |
|              | Wildcard keyframes |    N/A    |    ✅     |    ❌    |     ❌     |
|              |    Relative values |     ❌     |    ✅     |    ❌    |     ❌     |
| **Output**   |     Element styles |     ✅     |    ✅     |    ✅    |     ✅     |
|              |      Element attrs |     ❌     |    ❌     |    ✅    |     ✅     |
|              |  Custom animations |     ❌     |    ✅     |    ✅    |     ✅     |
| **Options**  |           Duration |     ✅     |    ✅     |    ✅    |     ✅     |
|              |          Direction |     ✅     |    ✅     |    ✅    |     ✅     |
|              |             Repeat |     ❌     |    ✅     |    ✅    |     ✅     |
|              |              Delay |     ❌     |    ✅     |    ✅    |     ✅     |
|              |          End delay |     ❌     |    ✅     |    ✅    |     ✅     |
|              |       Repeat delay |     ❌     |    ✅     |    ❌    |     ✅     |
| **Stagger**  |            Stagger |     ❌     | ✅ +.1kb  |    ✅    |     ✅     |
| **Timeline** |           Timeline |     ❌     | ✅ +.6kb  |    ✅    |     ✅     |
| **Controls** |               Play |     ✅     |    ✅     |    ✅    |     ✅     |
|              |              Pause |     ❌     |    ✅     |    ✅    |     ✅     |
|              |             Finish |     ❌     |    ✅     |    ✅    |     ✅     |
|              |            Reverse |     ❌     |    ✅     |    ✅    |     ✅     |
|              |               Stop |     ❌     |    ✅     |    ✅    |     ✅     |
|              |      Playback rate |     ❌     |    ✅     |    ✅    |     ✅     |
| **Easing**   |             Linear |     ✅     |    ✅     |    ✅    |     ✅     |
|              |       Cubic bezier |     ✅     |    ✅     |    ✅    |     ✅     |
|              |              Steps |     ✅     |    ✅     |    ✅    |     ✅     |
|              |            Springs | ✅ +1.2kb  |  ✅ +1kb  |    ✅    |     ❌     |
|              |              Glide |     ❌     | ✅ +1.3kb |    ❌    | ✅ $99/yr  |
|              |   Custom easing fn |     ❌     |    ❌     |    ✅    |     ✅     |
| **Events**   |           Complete |     ✅     |    ✅     |    ✅    |     ✅     |
|              |             Cancel |     ^     |    ✅     |    ✅    |     ✅     |
|              |              Start |     ❌     |    ❌     |    ✅    |     ✅     |
|              |             Update |     ❌     |    ❌     |    ✅    |     ✅     |
|              |             Repeat |    N/A    |    ❌     |    ✅    |     ✅     |
| **Path**     |        Motion path |     ❌     |    ✅     |    ✅    | ✅ +9.5kb  |
|              |      Path morphing |     ❌     | ✅ (lib)  |   ✅ *   | ✅ $99/yr  |
|              |       Path drawing |     ✅     |    ✅     |    ✅    | ✅ $99/yr  |
| **Other**    |            license |    MIT    |   MIT    |   MIT   |  Custom   |
|              |   GPU acceleration |     ✅     |    ✅     |    ❌    |     ❌     |
|              |          IE11 (ew) |     ❌     |    ❌     |    ✅    |     ✅     |
|              |            ReactJS | ✅ +0.1kb  |    ❌     |    ❌    |     ❌     |
|              |            SolidJS | ✅ +0.25kb |  ✅ +2kb  |    ❌    |     ❌     |
|              |             Vue.js | ✅ +0.6kb  |  ✅ +1kb  |    ❌    |     ❌     |
|              |             Svelte | ✅ +0.4kb  |    ❌     |    ❌    |     ❌     |

_\* must have the same number of points (Path morphing in AnimeJS)_

---
_Source: https://npm.io/package/crossani · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._