Repository navigation
leptos_motion: core animation primitives — tweened/spring signals and enter/leave transitions — for Leptos #4849
Replies: 2 comments 1 reply
|
(Note: Please see our AI Policy if applicable, particularly the heading "Do not copy-paste AI output to communicate with other people.") You and I probably have different ideas about what belongs in the core library as opposed to being in a third-party crate. My point of view: something that can be implemented in a third-party crate probably should be implemented in a third-party crate, solely because of the maintenance burden. "This belongs in a third-party crate" means "I'm willing to create and maintain this for as long as I need it." "This belongs in the core library" means "You, gbj, should be responsible for maintaining this in perpetuity, or breaking all users." This is especially true for domains about which I know nothing, including animation. I'm exactly the wrong person to review or maintain an animation library; but if an animation library is merged into the core of the framework, I will be responsible for maintaining it long-term. If there are things that need to change in the core library, or that need public API access to library internals, in order to implement a third-party animation library—I'm very open to those PRs. |
|
Thanks, that's a fair point, I hadn't thought about the maintenance burden on your side. If motion lives in the core, it's your code to maintain forever, so I get why it should be a separate crate. I'll follow that direction: I'll build it as a third-party crate. And if at some point I need the core to expose something that's currently internal, I'll open a small, focused PR for it, you mentioned you'd be open to that, and I'll keep them minimal. (And sorry for the long first message, first contribution, I wanted to be thorough.) |
Uh oh!
There was an error while loading. Please reload this page.
Title: leptos_motion: core animation primitives — tweened/spring signals and enter/leave transitions — for Leptos
Context / Motivation
Leptos is a fully reactive, fine-grained framework, yet it ships no animation or motion primitives. Compared with Svelte 5, which provides svelte/motion (tweened, spring) and svelte/transition (fade, fly, scale, slide, plus keyed transition: blocks), Leptos today offers only:
leptos::Transition (leptos/src/transition.rs) — an async/Suspense boundary (fallback + pending state). It renders between async states; it is not an animation primitive.
leptos::AnimatedShow (leptos/src/animated_show.rs) — class-based enter/leave (props show_class/hide_class + hide_delay) that unmounts after a set_timeout delay. The exit does not animate; it only postpones unmount.
leptos::For / tachys::view::keyed — keyed list rendering (an anchor for a future keyed ), with no enter/leave hooks.
There is no interpolation anywhere in the framework: no tweened/spring signals, no easing functions, no numeric Interpolate trait. A grep of the repo for easing|tween|spring|interpolat yields only false positives (e.g. interpolator 0.5 in Cargo.lock, a proc-macro dep of rstml), and codee (workspace dep 0.3.5) is a signal codec crate (used by leptos_server), not an interpolation engine.
A search of leptos-rs/leptos issue/PR titles for motion, tween, spring, or easing returns zero hits, so the gap is real and unclaimed inside the org.
Prior art inside the repo: router animations
Animation in the router is the strongest signal of demand — and of how hard property-driven directives get wrong:
AnimatedRoutes / AnimatedOutlet (removed in 0.7) were buggy and were abandoned in favor of the View Transition API in PR #3112 (“wip feat: use View Transition API for router animations”, gbj, merged 2024-10-19). The PR description explicitly cites the old approach's problems (#1754, #2058): it relied on cloning the view and keeping two copies in memory during a transition.
Older fixes in that area: PR #1204 (“fix: animations on multiple back navigations”, closes #1088) and the unmerged draft PR #1819 (“fix: router animations should reset to Start state”, closes #1754).
View Transitions later still produced a reported visual glitch (#4352, closed not_planned 2026-05-08).
View Transitions are a browser-level page/flash transition mechanism and complement — but do not replace — framework-level value interpolation.
The ecosystem is filling this gap with third-party crates
Several outside crates exist, but none is maintained inside the org and compatibility is mixed:
leptos_animation (Paul Wagener, crates.io leptos_animation v0.5.2) — derived animated signals via a single shared window.request_animation_frame() loop (AnimationContext, create_animated_signal, tween_default, easing). Last updated 2024-05; ~10k downloads; targets earlier Leptos versions.
leptos-motion (cloud-shuttle, repo cloud-shuttle/leptos-motion) — a “Motion-inspired” library (MotionDiv, WAAPI/RAF engines, spring physics, WebGL claims). Its crates.io versions (leptos-motion, leptos-motion-core, leptos-motion-studio) are currently yanked with max version 0.0.0, so the name is claimed but effectively unavailable.
slik (Wavyte, crates.io slik v0.2.0) — “binder-first Motion-inspired animation framework for Leptos”, published 2026-03, 42 downloads. [repo link unverified — GitHub returned 404 on read]
leptos-animated-for (brofrain) — FLIP position transitions for keyed lists (v0.4.8, ~27.5k downloads) — relevant prior art for a keyed TransitionGroup.
leptos-use (Synphonyte, v0.19.0, ~1.1M downloads) — a large utility collection; its source listing contains use_prefers_reduced_motion but no tweened/spring/transition engine.
Why core, not another 3P crate
motion are the kind of primitives Svelte owns in the framework because they touch the reactivity/runtime contract: they must be SSR-safe by construction, performant by default, and composable with signals/effects. Leptos 0.9 already provides the three pieces a motion engine needs, so this fits naturally as a workspace member (precedent: leptos_meta, leptos_router — separate crates that depend on leptos).
Current building blocks (verified in 0.9.0-beta)
leptos_dom::helpers::request_animation_frame(cb: impl FnOnce() + 'static) -> Result<AnimationFrameRequestHandle, JsValue> (leptos_dom/src/helpers.rs:227); AnimationFrameRequestHandle is Copy with .cancel() (helpers.rs:126). Re-exported through leptos::prelude::*. Both timers and rAF are cleaned up with the reactive Owner (on_cleanup) when an owner is current.
reactive_graph::signal::rw::RwSignal<T, S = SyncStorage> (reactive_graph/src/signal/rw.rs) — Copy + 'static, arena-allocated, .set/.update/.write/.with, auto-notifies subscribers. Also ArcRwSignal for ref-counted use.
reactive_graph::signal::trigger::Trigger (reactive_graph/src/signal/trigger.rs) — a data-less notification signal; the natural tick source for a driver loop.
Effects run only under the effects feature (reactive_graph/Cargo.toml:54); leptos enables it for csr/hydrate but not for ssr. ⇒ If the animation loop is started from an Effect, it never runs during SSR — SSR-safe by construction. AnimatedShow already relies on this.
Workspace: edition 2024, rust-version = 1.88, leptos = 0.9.0-beta; web-sys = 0.3 (default-features = false); new cfgs must be declared in [workspace.lints.rust] unexpected_cfgs.check-cfg; the CI feature matrix (cargo-all-features/skip_feature_sets) must be respected.
Proposal
Add a motion/ workspace member (published as leptos_motion) implementing core motion primitives bottom-up, with no unsafe, combinable, and performant by default (CONTRIB-GUIDE.md §5). Component-style, Svelte-like API (not use: directives — Leptos prefers components).
Phase 1 (numeric core, no DOM):
Key implementation notes (from the repo analysis):
Do not recreate an Effect per frame (that rewires subscriptions); use a self-sustaining driver: state in a StoredValue + output RwSignal, started from a single Effect (SSR-safe), re-scheduling via request_animation_frame under the captured Owner.
request_animation_frame is FnOnce, so the next frame must be re-requested inside the callback, and the Closure is only auto-cleaned when an Owner is current (see own_closure, helpers.rs). The driver must capture Owner::current() at start and on_cleanup must cancel the handle (see also #2330, closure-leak risk on cancelled rAF/timeouts).
Hot path: use RwSignal::update/.write() in place; no per-frame TweenOptions; scalar interpolation alloc-free. String/color interpolation deferred to stretch.
Never call window()/request_animation_frame during SSR render (panics in ssr-only builds); rely on the effects feature-gate + is_browser() checks in hydrate.
motion depends only on reactive_graph (+ leptos_dom rAF) for PR1 — no DOM component code until PR2, so numeric core is testable in native.
### Proposed PR plan
PR 1 — Interpolation core (minimum viable): crate motion/ with Interpolate (numerics + bool), easing (linear + cubic), Tweened/tweened(), and optionally Spring/spring(). Zero DOM component code; pure step() drivers exposed and natively tested (activate the effects feature in tests, as existing leptos_dom tests do). CR: small, self-contained, touches no renderer. → question: is tweened alone (sans spring) an acceptable minimum?
PR 2 — Enter transitions: Fade/Fly/Scale/Slide built on PR1 + reactive style:; SSR renders final state.
PR 3 — Exit + integration: generalize AnimatedShow for out-animations (keep-mounted while out runs), optional re-export in leptos::prelude, an example in examples/ (registered in examples/Makefile.toml), and a book chapter.
PR 4 — Keyed TransitionGroup (stretch): keyed enter/leave over /tachys::view::keyed; color (Rgba)/string interpolators.
Open questions to the community
Is a first-party motion crate in the core org wanted (vs. leaving it to the ecosystem)?
Naming: leptos_motion? Note leptos-motion is claimed (though yanked) on crates.io by a 3P author; leptos_animation is taken by PaulWagener; slik is 3P. Should we negotiate/avoid? Alternatives: leptos_motion, leptos_transitions…?
Crate vs module: separate workspace member motion/ (precedent leptos_meta/leptos_router) vs. a module in leptos proper?
Base branch: target leptos_0.9 (verified active, HEAD 2026-07-23) or main? Does this discussion live on main while PRs target the 0.9 line?
Minimal PR 1 scope that maintainers would accept: tweened + easing + Interpolate only, or also spring?
Should we collaborate with / build on existing 3P work (e.g. leptos_animation's shared-rAF-loop design, leptos-animated-for's FLIP, slik, cloud-shuttle/leptos-motion) rather than starting from scratch? Any maintainer preference?
Additional notes / checklist for the first PR
New crate must declare any new cfg in [workspace.lints.rust] unexpected_cfgs.check-cfg and respect cargo-all-features skip_feature_sets (csr+ssr, csr+hydrate, ssr+hydrate) and max_combination_size = 2.
#![deny(missing_docs)] (as leptos/src/lib.rs:1); workspace edition = "2024", rust-version = "1.88".
cargo +nightly fmt (stable rustfmt breaks CI), cargo +nightly make check, cargo +nightly make test; example requires check-examples.
Name-collision guard: do not shadow leptos::Transition (async) — use Fade/Fly/Scale/Slide/Tweened/Spring.
Naming/design probably deserves an ADR if this is accepted.
Verified facts
Repo state (leptos-rs/leptos)
Branch leptos_0.9 exists and is active: https://github.com/leptos-rs/leptos/tree/leptos_0.9 — HEAD commit 2026-07-23 “feat: surface failed lazy-route chunk loads to ErrorBoundary instead of panicking (#4785)” (GitHub REST API, GET /repos/leptos-rs/leptos/branches/leptos_0.9, fetched 2026-08-03).
Workspace version/edition: local Cargo.toml — leptos = { path = "./leptos", version = "0.9.0-beta" }, edition = "2024", rust-version = "1.88"; members include reactive_graph, leptos_dom, tachys, router, meta, any_error.
Local symbols verified by grep: AnimatedShow at leptos/src/animated_show.rs:51; request_animation_frame at leptos_dom/src/helpers.rs:227, AnimationFrameRequestHandle at leptos_dom/src/helpers.rs:126. (Symbol/line facts from docs/sintergic/design/analysis/motion-analysis.md, cross-checked by grep.)
Issues / PRs in leptos-rs/leptos (titles verified via GitHub Search/Issues REST API, fetched 2026-08-03)
PR #3112 — “(wip) feat: use View Transition API for router animations” (gbj, merged 2024-10-19): #3112
Issue #1754 — “AnimatedRoutes causes outlet to not transition on first click” (closed, completed 2024-10-20): #1754
Issue #2058 — “Using and set_is_routing in together leads to Hydration Bugs” (closed 2024-10-20): #2058
PR #1204 — “fix: animations on multiple back navigations (closes #1088)” (merged 2023-06-17): #1204
PR #1819 — “fix: router animations should reset to Start state (closes #1754)” (draft, never merged): #1819
Issue #4352 — “Visual glitch at the end of router View Transition” (closed as not_planned 2026-05-08): #4352
Issue #2330 — “Cancelling a timeout or animation frame request leaks the associated closure” (closed completed 2024-02-20): #2330
Search repo:leptos-rs/leptos motion in:title → 0 results; repo:leptos-rs/leptos tween OR spring OR easing in:title → 0 results (GitHub Search API, 2026-08-03).
Ecosystem crates (crates.io REST API / docs.rs, fetched 2026-08-03)
leptos_animation v0.5.2, ledger 10,192 downloads, created 2023-06-29, last update 2024-05-15, NOT yanked, WTFPL, repo https://github.com/PaulWagener/leptos_animation (26★); docs https://docs.rs/leptos_animation/latest/leptos_animation/.
leptos-motion / leptos-motion-core / leptos-motion-studio — crates.io search result: yanked=true, max_version 0.0.0, repo https://github.com/cloud-shuttle/leptos-motion (12★, MIT, README claims v0.8.3); homepage https://leptos-motion.dev/.
slik v0.2.0, 42 downloads, created 2026-03, NOT yanked, keywords [animation, leptos, motion, spring, wasm], “binder-first Motion-inspired animation framework for Leptos”, repo field https://github.com/Wavyte/slik (GitHub page returned 404 when read on 2026-08-03 → repo link UNVERIFIED).
leptos-animated-for v0.4.8, 27,551 downloads, NOT yanked, “component utilizing FLIP position transitions for Leptos”, repo https://github.com/brofrain/leptos-animated-for.
leptos-use v0.19.0, ~1.1M downloads, NOT yanked, repo https://github.com/Synphonyte/leptos-use; src listing contains use_prefers_reduced_motion.rs but no tween/spring/transition modules (GitHub contents API, 2026-08-03).
Unverified / not confirmed
No GitHub Discussion thread on leptos motion/animation could be confirmed (Discussions API requires auth; web search did not surface one). Marked as open question Q6 in case one exists.
Issue #1088 is referenced by PR #1204's title (“closes #1088”), but its own title/content was not independently fetched — treat #1088 as “older AnimatedRoutes bug fixed by #1204”.
Wavyte/slik GitHub repository (https://github.com/Wavyte/slik) returned 404 when read on 2026-08-03 — crate exists on crates.io, repo link unverifiable.
cloud-shuttle/leptos-motion claimed version v0.8.3 (repo README) conflicts with crates.io showing all versions yanked at max 0.0.0 — exact crate status is ambiguous; treat as “name claimed, currently unavailable on crates.io”.
Whether the repo's codee dependency (0.3.5) could later be reused for signal codecs vs. motion interpolation is not investigated further — treated as out of scope.
The blog post “Building Modern Animation Infrastructure for Leptos and Rust Frontends” (Medium) was surfaced but not treated as a source of fact.
All reactions