live_motion: A JavaScript repository from benvp

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

Documentation

You can find the full API documentation on hexdocs.pm/live_motion.

Additionally you can find a few examples here: LiveMotion Examples.

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 benvp.co. It's very subtle, but when you navigate, you see the page transitions.
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.3"}
  ]
end

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
  // ...
  ...motionHook,
};

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 },
  hooks,
  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.

Show Instructions for npm / yarn

We need to add the JS part as a dependency to our package.json file. Add this to your package.json file.

{
  "dependencies": {
    "live_motion": "file:../deps/live_motion"
  }
}

Don't forget to run npm install or yarn afterwards.

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. Rendering any HTML element will be supported when LiveView 0.18.0 is ready.
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.
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.