Skip to content
use-legend

useThrottledHistory

A hook that tracks Observable change history with throttle. A thin wrapper around useHistory with throttleFilter applied — for rapidly changing values like sliders or drag interactions, it records snapshots at fixed intervals instead of on every change.

Demo

Section titled “Demo”
Throttled Sampling
Capture motion without noise

For fast-moving values like sliders, history records at most once every 300ms instead of saving every intermediate frame.

Sampled slider

Drag aggressively and notice how the timeline keeps only periodic checkpoints.

Up to 1 commit / 300ms
Value: 50
Throttled timeline

Newest snapshot is pinned at the top.

#1
50

Usage

Section titled “Usage”
import { 
function useObservable<T>(): Observable<T | undefined> (+3 overloads)
A React hook that creates a new observable
@param ― initialValue The initial value of the observable or a function that returns the initial value
@see ― https://www.legendapp.com/dev/state/react/#useObservable
useObservable } from "@legendapp/state/react";
import { 
import useThrottledHistory
useThrottledHistory } from "@usels/web";


const 
const slider$: any
slider$ = 
useObservable<unknown>(value: Promise<unknown> | (() => unknown) | unknown, deps?: React.DependencyList): any (+3 overloads)
A React hook that creates a new observable
@param ― initialValue The initial value of the observable or a function that returns the initial value
@see ― https://www.legendapp.com/dev/state/react/#useObservable
useObservable(50);


// Record at most once every 300ms
const { 
const undo: any
undo, 
const redo: any
redo, 
const canUndo$: any
canUndo$ } = 
import useThrottledHistory
useThrottledHistory(
const slider$: any
slider$, { 
throttle: number
throttle: 300 });

leading / trailing edges

Section titled “leading / trailing edges”

By default both leading and trailing edges fire. Disable either to customize behavior.

import { 
function useObservable<T>(): Observable<T | undefined> (+3 overloads)
A React hook that creates a new observable
@param ― initialValue The initial value of the observable or a function that returns the initial value
@see ― https://www.legendapp.com/dev/state/react/#useObservable
useObservable } from "@legendapp/state/react";
import { 
import useThrottledHistory
useThrottledHistory } from "@usels/web";


const 
const value$: any
value$ = 
useObservable<unknown>(value: Promise<unknown> | (() => unknown) | unknown, deps?: React.DependencyList): any (+3 overloads)
A React hook that creates a new observable
@param ― initialValue The initial value of the observable or a function that returns the initial value
@see ― https://www.legendapp.com/dev/state/react/#useObservable
useObservable(0);


// Only record on the trailing edge (end of throttle window)
const { 
const undo: any
undo } = 
import useThrottledHistory
useThrottledHistory(
const value$: any
value$, {
  
throttle: number
throttle: 500,
  
leading: boolean
leading: false,
  
trailing: boolean
trailing: true,
});

Combined with capacity

Section titled “Combined with capacity”
import { 
function useObservable<T>(): Observable<T | undefined> (+3 overloads)
A React hook that creates a new observable
@param ― initialValue The initial value of the observable or a function that returns the initial value
@see ― https://www.legendapp.com/dev/state/react/#useObservable
useObservable } from "@legendapp/state/react";
import { 
import useThrottledHistory
useThrottledHistory } from "@usels/web";


const 
const position$: any
position$ = 
useObservable<unknown>(value: Promise<unknown> | (() => unknown) | unknown, deps?: React.DependencyList): any (+3 overloads)
A React hook that creates a new observable
@param ― initialValue The initial value of the observable or a function that returns the initial value
@see ― https://www.legendapp.com/dev/state/react/#useObservable
useObservable({ 
x: number
x: 0, 
y: number
y: 0 });


const { 
const undo: any
undo, 
const redo: any
redo } = 
import useThrottledHistory
useThrottledHistory(
const position$: any
position$, {
  
throttle: number
throttle: 200,
  
capacity: number
capacity: 20, // keep at most 20 throttled snapshots
});

Type Declarations

Section titled “Type Declarations”
export type UseThrottledHistoryOptions<Raw, Serialized = Raw> = Omit<UseHistoryOptions<Raw, Serialized>, "eventFilter"> & {
    throttle?: MaybeObservable<number>;
    trailing?: boolean;
    leading?: boolean;
};
export type UseThrottledHistoryReturn<Raw, Serialized = Raw> = UseHistoryReturn<Raw, Serialized>;
export declare function useThrottledHistory<Raw, Serialized = Raw>(source$: Observable<Raw>, options?: DeepMaybeObservable<UseThrottledHistoryOptions<Raw, Serialized>>): UseThrottledHistoryReturn<Raw, Serialized>;

Source

Section titled “Source”

View on GitHub

Contributors

Section titled “Contributors”
  • tigerwest

Changelog

Section titled “Changelog”
  • a7392ab 2026-03-06 - feat(core,browser): add sync strategy hooks (tigerwest)