<h1><img src="" alt="🍿 LiveMotion" width="400"></h1>

LiveMotion enables high performance animations declared on the server and run on the client.

## Features

- Define animations declaratively directly in your HEEX templates. No definition of CSS
  classes or keyframes required.
- Animate page transitions using mount/unmount animations. See a little example
  at [](
- Trigger animations directly on the client using `LiveMotion.JS` (e.g. button clicks).

## Installation

LiveMotion makes use of Phoenix LiveView hooks and therefore the setup requires a few more steps than just adding the dependency to the Mixfile. However, the JS part is included and works without node installed.

Add the `live_motion` dependency to your `mix.exs` file.

def deps do
    {:live_motion, "~> 0.1.0"}

Open up your `app.js` and import `createLiveMotion` and initialize LiveMotion.

import { createLiveMotion } from 'live_motion';

const { hook: motionHook, handleMotionUpdates } = createLiveMotion();

Now in your hook definition, add the LiveMotion hook.

const hooks = {
  // your other hooks
  // ...

Finally, we need to make sure that LiveView does not overwrite the style attributes generated by LiveMotion. In your `LiveSocket` initialization, add the following function into `onBeforeElUpdated(from, to)`.

let liveSocket = new LiveSocket('/live', Socket, {
  params: { _csrf_token: csrfToken },
  dom: {
    onBeforeElUpdated(from, to) {
      // add this line
      handleMotionUpdates(from, to);

If you are using node and have npm or yarn installed, one additional step is required.

  <summary>Show Instructions for npm / yarn</summary>

We need to add the JS part as a dependency to our package.json file. From the root directory of your project, run the following command.

If you are using npm:

npm install --prefix assets --save ../deps/live_motion

If you are using yarn:

yarn add --cwd assets file:../deps/live_motion


### Roadmap

There are still a lot of things to do to get to a mature library.

- Add tests
- Improve documentation
- See the limitations section.

### Limitations

LiveMotion is still in the early days, so breaking changes are expected. Additionally, there
are still a few limitations, which will be added in future releases.

- `LiveMotion.motion` always renders as a `div` element. There are plans on providing
  an api to support rendering any HTML element.
- Currently standard easing functions (e.g. `ease-in-out`, bezier curves) and spring
  animations are supported. Due to the nature of spring animations, they do not have
  a fixed duration (theoretically they can run indefinetely). When using unmount transition,
  this adds a challenge, as we do not know how long Phoenix LiveView should defer the actual
  removal of the DOM node. For now, we fall back to the maximum supported duration of ten seconds.
- Support Stagger and glide animations will be added in a later release.
- Layout animations are not yet supported. Think of animations which automatically move
  items in the correct place after an element is removed which affects the layout.

## Contributing

Any contribution is very much welcome. The project itself works just as any other mix project.

Please do not include an updated `priv/static/live_view.js` in pull requests. The maintainers will update it as part of the release process.