Vanilla motion values

Everything the use* motion-value hooks do, without a component: create values in module scope, .svelte.ts stores, or event handlers, and bind them straight to plain DOM elements with styleEffect — mirroring Motion’s “vanilla JavaScript” API.

// stores/scroll.svelte.ts — impossible with useMotionValue
import { motionValue } from '@humanspeak/svelte-motion'

export const scrollProgress = motionValue(0)
// stores/scroll.svelte.ts — impossible with useMotionValue
import { motionValue } from '@humanspeak/svelte-motion'

export const scrollProgress = motionValue(0)
mode · live running
// vanilla-values progress 20%
toMotionValue → mapValue → springValue → styleEffect no motion.* components

Hooks vs vanilla

Both layers return the same augmented value: a real motion-dom MotionValue (passes isMotionValue, works with animate()) with a rune-reactive .current and a store .subscribe. The only difference is lifecycle:

use* hooksVanilla factories
Where they workComponent init onlyAnywhere
CleanupAutomatic on unmountManual .destroy()
ExamplesuseMotionValue, useSpring, useTransformmotionValue, springValue, transformValue, mapValue

Values that live for the app’s lifetime (module-scope stores) never need destroying. Values created per-interaction should be destroyed when done — a getter-bridged value holds a live Svelte effect until then.

The factories

import { mapValue, motionValue, springValue, transformValue } from '@humanspeak/svelte-motion'

const x = motionValue(0)

// Range mapping — numbers, colors, unit strings
const opacity = mapValue(x, [0, 200], [1, 0])
const color = mapValue(x, [0, 200], ['#ff0088', '#00ccff'])

// Springs toward a source (values or unit strings)
const smooth = springValue(x, { stiffness: 300, damping: 30 })

// Computed from .get() reads — dependencies auto-tracked
const label = transformValue(() => `${Math.round(x.get())}px`)
import { mapValue, motionValue, springValue, transformValue } from '@humanspeak/svelte-motion'

const x = motionValue(0)

// Range mapping — numbers, colors, unit strings
const opacity = mapValue(x, [0, 200], [1, 0])
const color = mapValue(x, [0, 200], ['#ff0088', '#00ccff'])

// Springs toward a source (values or unit strings)
const smooth = springValue(x, { stiffness: 300, damping: 30 })

// Computed from .get() reads — dependencies auto-tracked
const label = transformValue(() => `${Math.round(x.get())}px`)

springValue and mapValue accept any source kind: a MotionValue, a Svelte readable store, or a reactive getter.

toMotionValue — the rune bridge

Turn any Svelte state into a motion value. The getter form tracks $state / $derived reads (and other augmented values’ .current):

<script lang="ts">
    import { styleEffect, toMotionValue } from '@humanspeak/svelte-motion'

    let progress = $state(0)
    const opacity = toMotionValue(() => progress / 100)

    let el = $state<HTMLElement | null>(null)
    $effect(() => {
        if (!el) return
        const stop = styleEffect(el, { opacity })
        return () => stop()
    })
</script>

<input type="range" bind:value={progress} />
<div bind:this={el}>Fades with the slider</div>
<script lang="ts">
    import { styleEffect, toMotionValue } from '@humanspeak/svelte-motion'

    let progress = $state(0)
    const opacity = toMotionValue(() => progress / 100)

    let el = $state<HTMLElement | null>(null)
    $effect(() => {
        if (!el) return
        const stop = styleEffect(el, { opacity })
        return () => stop()
    })
</script>

<input type="range" bind:value={progress} />
<div bind:this={el}>Fades with the slider</div>

Passing an existing MotionValue returns the same value; passing a readable store returns a mirroring value. Getter-driven updates flush on Svelte’s effect schedule (a microtask), matching template timing.

The hooks understand getters too — useSpring(() => target) and useTransform(() => count, [0, 10], [0, 100]) track rune state the same way.

Element effects

Bind values directly to elements — no motion component in sight:

import { attrEffect, styleEffect, svgEffect } from '@humanspeak/svelte-motion'

const stop = styleEffect('.box', { x, opacity })      // inline styles
attrEffect(input, { value: count })                    // attributes
svgEffect(path, { pathLength: progress })              // SVG attributes
import { attrEffect, styleEffect, svgEffect } from '@humanspeak/svelte-motion'

const stop = styleEffect('.box', { x, opacity })      // inline styles
attrEffect(input, { value: count })                    // attributes
svgEffect(path, { pathLength: progress })              // SVG attributes

Each returns an unbind function. Import them from this package (not motion) so both raw and augmented values type-check.

Need to drive something that isn’t an element? See Custom effects.

Scheduler, generators, config

The rest of Motion’s vanilla toolkit re-exports directly:

import {
    cancelFrame,
    frame,            // frameloop scheduler: frame.read / frame.update / frame.render
    MotionGlobalConfig, // e.g. skipAnimations for tests
    processFrame,     // process a frame now, e.g. from an XRSession loop
    scrollInfo,
    spring            // spring generator for WAAPI / custom drivers
} from '@humanspeak/svelte-motion'

frame.render(() => {
    // runs on Motion's render step this frame
})
import {
    cancelFrame,
    frame,            // frameloop scheduler: frame.read / frame.update / frame.render
    MotionGlobalConfig, // e.g. skipAnimations for tests
    processFrame,     // process a frame now, e.g. from an XRSession loop
    scrollInfo,
    spring            // spring generator for WAAPI / custom drivers
} from '@humanspeak/svelte-motion'

frame.render(() => {
    // runs on Motion's render step this frame
})

Driving frames yourself

processFrame() (Motion 14.6) runs every frameloop step (setup, read, resolveKeyframes, preUpdate, update, preRender, render, postRender) right now, instead of waiting for the next requestAnimationFrame. Use it when something other than requestAnimationFrame drives your frames, like an XRSession during an immersive WebXR session. Wherever requestAnimationFrame does fire, Motion keeps processing frames from it too. Calls made inside a frame are ignored.

@humanspeak/svelte-motion/three writes to meshes on frame.preRender, so a WebXR renderer.setAnimationLoop callback can call processFrame() before rendering to keep Motion in step:

renderer.setAnimationLoop(() => {
    processFrame()
    renderer.render(scene, camera)
})
renderer.setAnimationLoop(() => {
    processFrame()
    renderer.render(scene, camera)
})

For a timeline you control (tests, video export), turn on manual timing and pass each frame’s time in milliseconds:

MotionGlobalConfig.useManualTiming = true

for (let ms = 0; ms <= 1000; ms += 1000 / 60) {
    processFrame(ms)
}
MotionGlobalConfig.useManualTiming = true

for (let ms = 0; ms <= 1000; ms += 1000 / 60) {
    processFrame(ms)
}

Without manual timing, the frame delta is clamped to 1–40 ms, like the requestAnimationFrame loop.

Animations Motion normally hands to the browser (WAAPI), like opacity or transform on an HTML or SVG element, follow the browser’s clock. While useManualTiming is on, Motion runs those in JS instead, so they follow your timestamps. The exceptions are view transitions, optimized appear animations, and colours only the browser can mix (like oklch()), which jump to their end.

Plus the steps, mirrorEasing, and reverseEasing easing helpers alongside the existing easing exports.

Related


Based on Motion’s vanilla motion value API.