Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/benvp/live_motion
High performance animation library for Phoenix LiveView
https://github.com/benvp/live_motion
Last synced: 4 days ago
JSON representation
High performance animation library for Phoenix LiveView
- Host: GitHub
- URL: https://github.com/benvp/live_motion
- Owner: benvp
- License: mit
- Created: 2022-04-07T11:47:36.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2023-09-11T19:26:59.000Z (about 1 year ago)
- Last Synced: 2024-04-25T22:43:12.605Z (7 months ago)
- Language: JavaScript
- Size: 268 KB
- Stars: 201
- Watchers: 7
- Forks: 11
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
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](https://hexdocs.pm/live_motion/LiveMotion.html).
Additionally you can find a few examples here: [LiveMotion Examples](https://livemotion.benvp.co).
## 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](https://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.
```elixir
def deps do
[
{:live_motion, "~> 0.3"}
]
end
```
Open up your `app.js` and import `createLiveMotion` and initialize LiveMotion.
```js
import { createLiveMotion } from 'live_motion';
const { hook: motionHook, handleMotionUpdates } = createLiveMotion();
```
Now in your hook definition, add the LiveMotion hook.
```js
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)`.
```js
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.
```json
{
"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.
Please do not include an updated `priv/static/live_motion.js` in pull requests. The maintainers will update it as part of the release process.