Elm Motion

A comprehensive Elm package for smooth, high-performance DOM animations and scrolling.

✨ Highlights

• 6 animation engines + 3 scroll engines — one builder API
• Define once, run with any engine — swap engines without rewriting your animations
• Three timelines, one API — drive motion by time, scroll progress or viewport position
• Mid-flight control — query, divert, pause, resume, restart and stop motion in flight
• Hardware-accelerated — GPU transforms with full 3D support
• Composable — build animations from small, reusable builder pieces
• Type-safe — only the capabilities an engine actually supports compile against it
• Reduced-motion aware — the WAAPI-based engines honour prefers-reduced-motion: reduce

🎯 One API, many engines

Define an animation once, then run it with any engine — no rewrites:

fadeIn : AnimBuilder eng -> AnimBuilder eng
fadeIn =
    Opacity.begin 
        >> Opacity.from 0 
        >> Opacity.to 1 
        >> Opacity.end

Transition.animate model.animState <|
    Transition.for "entrance" 
        >> fadeIn

Keyframe.animate model.animState <|
    Keyframe.for "entrance"
        >> fadeIn

Sub.animate model.animState <|
    Sub.for "entrance"
        >> fadeIn

-- … and WAAPI, ScrollTimeline and ViewTimeline take the same definition

Scrolling follows the same define-once philosophy across the Cmd, Task and Sub scroll engines.

🚦 Engines

Animation

• Transition — Browser-native; simple A→B, minimal control (stop, reset)
• Keyframe — Browser-native; full control, looping
• Sub — Pure Elm; full control, looping, real-time mid-flight queries/diversions
• WAAPI — Native via JS; full control, looping, real-time mid-flight queries/diversions
• ScrollTimeline — Native via JS; scroll-driven, tied to a container's scroll progress
• ViewTimeline — Native via JS; viewport-driven, tied to an element entering/leaving view

Scroll

• Cmd — Fire-and-forget, minimal setup
• Task — Composable, with typed error handling
• Sub — Stateful, with events and mid-scroll queries

🚀 Install

elm install phollyer/elm-motion

The WAAPI, ScrollTimeline and ViewTimeline engines also need the JavaScript companion:

npm install @phollyer/elm-motion

The companion carries its own version — any 1.x companion works with any 1.x Elm package.

📚 Getting started

Step-by-step guides for your first animation and first scroll live in the docs:

• Your first animation
• Your first scroll
• Engine overview

Full documentation, property reference and live examples: phollyer.github.io/elm-motion

🧩 JavaScript companion

See the npm package README for setup, port wiring and error reporting.

📋 Roadmap — in no particular order or timeframe

• CSS Transitions — potentially bake complex easings, and maybe springs, into the CSS linear easing function
• FLIP Engine
• Canvas Engine
• WebGL Engine
• Any other user-suggested features
• Dedicated website similar to motion.dev for React

💖 Sponsor

Elm Motion is free and open source, built in my own time. If it helps you or your team, please consider sponsoring on GitHub — monthly or a one-time amount. It directly supports ongoing development.

🙏 Credits

Uses code from linuss/smooth-scroll.

The JavaScript companion bundles scroll-timeline-polyfill (Apache-2.0).

📄 License

BSD-3-Clause