use-throttled

Create a readonly throttled view of a reactive source.

Usage

import { useThrottled } from "@vizejs/composable/use-throttled";

Runtime contract

API

useThrottled

Create a readonly throttled view of a reactive source. Changes are observed with flush: "sync", so every synchronous write counts. Outside a cooldown window, a change applies immediately when UseThrottledOptions.leading is enabled (otherwise it waits as a trailing update) and opens a window of waitMs milliseconds. Changes inside a window are collected as the trailing candidate; when the window ends with a candidate waiting, the source value current at that moment is applied and the next window opens back to back, keeping applications spaced by waitMs. A window that ends without a candidate closes silently. waitMs is reactive and is read each time a window opens; changing it never disturbs an already-open window. A wait of 0 still defers trailing updates to the next scheduler tick. Server rendering is explicit: without a browser window (and with UseThrottledOptions.runOnServer disabled) no timer ever starts and the view mirrors the source synchronously, so server-rendered output shows current values and nothing leaks. pending stays false and the controls report false in that mode. Cleanup rule: the watcher and any open window timer are released when the owning reactive scope stops; call inside an active scope. Outside one, the watcher lives as long as the source and cancel() only clears the window.

function useThrottled<Value>( source: MaybeRefOrGetter<Value>, waitMs: MaybeRefOrGetter<number>, options: UseThrottledOptions = {}, ): ThrottledControls<Value>

const scrollY = shallowRef(0);
const { throttled } = useThrottled(scrollY, 100);
scrollY.value = 40; // applied immediately (leading edge)
scrollY.value = 80; // applied when the 100ms window ends

Types

UseThrottledOptions

Options for useThrottled.

ThrottledControls

Reactive throttled view and controls returned by useThrottled.