useDebouncedHistory

A hook that tracks Observable change history with debounce. A thin wrapper around useHistory with debounceFilter applied — it only records history after typing has stopped. Ideal for text inputs or search fields where you want to snapshot only when a burst of changes has “settled”.

Demo

Debounced Commits

Only settled input gets saved

Rapid typing stays fluid, but history records only after the input has been idle for 600ms.

Settling editor

Type quickly, pause, then inspect how only the settled value lands in history.

Commit after 600ms

Debounce (ms)

Snapshots: 1

Debounced timeline

Newest snapshot is pinned at the top.

10:00:59 AM

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 useDebouncedHistory
useDebouncedHistory } from "@usels/web";

const 
const search$: any
search$ = 
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("");

// Record a snapshot 500ms after the user stops typing
const { 
const undo: any
undo, 
const redo: any
redo, 
const canUndo$: any
canUndo$ } = 
import useDebouncedHistory
useDebouncedHistory(
const search$: any
search$, { 
debounce: number
debounce: 500 });

maxWait — force commit after maximum delay

Even if the user keeps typing, a snapshot is forced after maxWait ms.

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 useDebouncedHistory
useDebouncedHistory } from "@usels/web";

const 
const text$: any
text$ = 
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("");

// Commit after 500ms idle, or every 2s at most even if still typing
const { 
const undo: any
undo, 
const redo: any
redo } = 
import useDebouncedHistory
useDebouncedHistory(
const text$: any
text$, {
  
debounce: number
debounce: 500,
  
maxWait: number
maxWait: 2000,
});

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 useDebouncedHistory
useDebouncedHistory } from "@usels/web";

const 
const note$: any
note$ = 
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("");

const { 
const undo: any
undo, 
const redo: any
redo } = 
import useDebouncedHistory
useDebouncedHistory(
const note$: any
note$, {
  
debounce: number
debounce: 800,
  
capacity: number
capacity: 30,
});

Type Declarations

export type UseDebouncedHistoryOptions<Raw, Serialized = Raw> = Omit<UseHistoryOptions<Raw, Serialized>, "eventFilter"> & {
    debounce?: MaybeObservable<number>;
    maxWait?: MaybeObservable<number>;
};
export type UseDebouncedHistoryReturn<Raw, Serialized = Raw> = UseHistoryReturn<Raw, Serialized>;
export declare function useDebouncedHistory<Raw, Serialized = Raw>(source$: Observable<Raw>, options?: DeepMaybeObservable<UseDebouncedHistoryOptions<Raw, Serialized>>): UseDebouncedHistoryReturn<Raw, Serialized>;

Source

View on GitHub

Contributors

tigerwest

Changelog

a7392ab 2026-03-06 - feat(core,browser): add sync strategy hooks (tigerwest)