smooth-value

A lightweight, framework-agnostic utility for creating smooth, spring-based animated values. Perfect for parallax effects, cursor followers, sliders, color pickers, scroll-driven animations, and any scenario where you need a value to smoothly chase a moving target.

Features

• Multi-framework support — First-class support for React, Vue, Preact, Solid, Svelte, and Lit, with more on the way.
• Tiny & tree-shakeable — Only bundles the adapter for the framework you import.
• FPS-aware — Automatically adjusts spring speed based on the current frame rate for consistent animation feel across devices.
• Reduced motion respect — Honors prefers-reduced-motion: reduce out of the box, with a manual override option.
• Single value or multi-values — Smoothly animate individual numbers, tuples, or arrays of numbers simultaneously.
• TypeScript-first — Fully typed with generics for both number and number[] usage.

Installation

# npm
npm install smooth-value

# yarn
yarn add smooth-value

# pnpm
pnpm add smooth-value

Important: Framework-Specific Imports

This library supports multiple frontend frameworks. Always import from the framework-specific entrypoint — never from the root package:

// ✅ Correct — explicitly specifies the framework
import { useSmoothValue } from "smooth-value/react";
import { useSmoothValue } from "smooth-value/vue";
import { useSmoothValue } from "smooth-value/svelte";

// ❌ Wrong — root import is not supported
import { useSmoothValue } from "smooth-value";

Roadmap

| Framework | Status | | ---------- | ------ | | React | ✅ Supported | | Vue | ✅ Supported | | Preact | ✅ Supported | | Solid | ✅ Supported | | Svelte | ✅ Supported | | Lit | ✅ Supported | | Angular | 🚧 In progress | | Qwik | 🚧 In progress | | Ember | 🚧 In progress | | Marko | 🚧 In progress |

Usage

Parameters

The useSmoothValue hook function accepts the following arguments (the exact type signature varies slightly per framework — see the examples below):

| Parameter | Type | Required | Default | Description | | ----------- | --------------------------------- | -------- | ------- | ----------- | | current | Varies by framework (see below) | Yes | — | The target value to smoothly animate toward. Accepts number or number[]. | | spring | number | No | 0.5 | Smooth speed factor in the range (0, 1]. Higher values are snappier; lower values are smoother. | | options | SmoothValueOptions<T> | No | {} | Configuration object (see below). |

The spring parameter value must be within (0, 1]. A RangeError is thrown otherwise.

SmoothValueOptions<T>

| Option | Type | Default | Description | | --------------- | ---------------------------------------- | ------------ | ----------- | | disabled | boolean | false | Force-disable smooth animation. When true, the value snaps immediately to the target. | | onChange | (current: T, previous: T) => void | undefined | Called every time the smooth value updates. | | onStopChange | (current: T, previous: T) => void | undefined | Called when the smooth value settles at the target. |

React

import { useState } from "react";
import { useSmoothValue } from "smooth-value/react";

function MouseFollower() {
  const [target, setTarget] = useState([0, 0]);

  const smooth = useSmoothValue(target, 0.3, {
    onChange: (cur, prev) => console.log(`Moving: ${prev} → ${cur}`),
    onStopChange: (cur, prev) => console.log(`Settled at ${cur}`),
  });

  return (
    <div onMouseMove={e => setTarget([e.clientX, e.clientY])}>
      <div style={{ translate: `${smooth[0]}px ${smooth[1]}px` }} />
    </div>
  );
}

In React, current is a plain state value (T), and the return value is the smooth state directly (T).

Vue

<script setup lang="ts">
  import { ref } from "vue";
  import { useSmoothValue } from "smooth-value/vue";

  const target = ref([0, 0]);

  const smooth = useSmoothValue(target, 0.3, {
    onChange: (cur, prev) => console.log(`Moving: ${prev} → ${cur}`),
    onStopChange: (cur, prev) => console.log(`Settled at ${cur}`),
  });
</script>

<template>
  <div @mousemove="e => target = [e.clientX, e.clientY]">
    <div :style="{ translate: `${smooth[0]}px ${smooth[1]}px` }" />
  </div>
</template>

In Vue, current accepts a MaybeRef<T> (a ref, computed, getter, or plain value), and the return value is a ComputedRef<T> (a readonly ref). Access .value inside <script>; template unwrapping is automatic.

Preact

import { useState } from "preact/hooks";
import { useSmoothValue } from "smooth-value/preact";

function MouseFollower() {
  const [target, setTarget] = useState([0, 0]);

  const smooth = useSmoothValue(target, 0.3, {
    onChange: (cur, prev) => console.log(`Moving: ${prev} → ${cur}`),
    onStopChange: (cur, prev) => console.log(`Settled at ${cur}`),
  });

  return (
    <div onMouseMove={e => setTarget([e.clientX, e.clientY])}>
      <div style={{ translate: `${smooth[0]}px ${smooth[1]}px` }} />
    </div>
  );
}

In Preact, current is a plain state value (T), and the return value is the smooth state directly (T). The API is identical to React.

Solid

import { createSignal } from "solid-js";
import { useSmoothValue } from "smooth-value/solid";

function MouseFollower() {
  const [target, setTarget] = createSignal([0, 0]);

  const smooth = useSmoothValue(target, 0.3, {
    onChange: (cur, prev) => console.log(`Moving: ${prev} → ${cur}`),
    onStopChange: (cur, prev) => console.log(`Settled at ${cur}`),
  });

  return (
    <div onMouseMove={e => setTarget([e.clientX, e.clientY])}>
      <div style={{ translate: `${smooth()[0]}px ${smooth()[1]}px` }} />
    </div>
  );
}

In Solid, current is an Accessor<T> (a getter function), and the return value is also an Accessor<T>. Call it (smooth()) to read the value.

Svelte

<script lang="ts">
  import { useSmoothValue } from "smooth-value/svelte";

  let target = $state(0);

  const getSmooth = useSmoothValue(() => target, 0.3, {
    onChange: (cur, prev) => console.log(`Moving: ${prev} → ${cur}`),
    onStopChange: (cur, prev) => console.log(`Settled at ${cur}`),
  });
</script>

<div onmousemove={e => target = [e.clientX, e.clientY]}>
  <div style="translate: {getSmooth()[0]}px {getSmooth()[1]}px" />
</div>

In Svelte, current is a getter function (() => T), and the return value is also a getter function (() => T). Call it as getSmooth() to read the value.

Note: The Svelte adapter uses Svelte 5's $state rune internally and requires Svelte 5+.

Lit

import { LitElement, html } from "lit";
import { useSmoothValue } from "smooth-value/lit";

class MouseFollower extends LitElement {
  private _target = 0;

  private _smooth = useSmoothValue(this, () => this._target, 0.3, {
    onChange: (cur, prev) => console.log(`Moving: ${prev} → ${cur}`),
    onStopChange: (cur, prev) => console.log(`Settled at ${cur}`),
  });

  render() {
    return html`
      <div @mousemove=${(e: MouseEvent) => this._target = [e.clientX, e.clientY]}>
        <div style="translate: ${this._smooth.value[0]}px ${this._smooth.value[1]}px"></div>
      </div>
    `;
  }
}

In Lit, useSmoothValue takes an extra first argument: the ReactiveControllerHost (your element instance, typically this). The second argument, current, is a getter function (() => T). The return value is a SmoothValueController whose .value property holds the current smooth value.

Advanced: Framework-Agnostic Core

The package smooth-value/framework-agnostic exports the underlying createSmoothValue function and the SmoothValueAdapter interface. This is intended for building adapters for frameworks not yet officially supported. Most users should use a framework-specific entrypoint instead.

Each framework package also exports a getSpringByFps utility for manual spring calculations at varying frame rates — this is an advanced API and not needed for typical usage.

How It Works

smooth-value uses requestAnimationFrame to continuously interpolate between the current smooth value and the target value using a spring formula. On each frame, it moves a fraction (spring speed) of the remaining distance toward the target, creating a natural deceleration curve. The spring speed is automatically adjusted based on the monitor's actual frame rate so the animation feels consistent whether you're at 60 Hz, 120 Hz, or higher.

When prefers-reduced-motion: reduce is detected (or the disabled option is set), the value snaps immediately to the target without any interpolation.

References

• Parallax smooth movement.

License

MIT