useObserveDebounced

Runs a reactive effect debounced — fires only after ms milliseconds of inactivity. Built on useObserveWithFilter. The selector always tracks dependencies; only the effect is debounced.

Usage

Hook

import { useObservable, useObserveDebounced } from "@usels/web";

function Component() {
  const query$ = useObservable("");

  // ✅ Effect fires only after query$ stops changing for 300ms
  useObserveDebounced(
    () => query$.get(),
    (value) => {
      console.log("search:", value);
    },
    { ms: 300 }
  );
}

Scope

import { observable, observeDebounced } from "@usels/web";

function Component() {
  "use scope"
  const query$ = observable("");

  // ✅ Effect fires only after query$ stops changing for 300ms
  observeDebounced(
    () => query$.get(),
    (value) => {
      console.log("search:", value);
    },
    { ms: 300 }
  );
}

With maxWait

Use maxWait to guarantee the effect fires at least once, even if the source keeps changing continuously. The effect will fire after maxWait milliseconds regardless of activity.

Hook

import { useObservable, useObserveDebounced } from "@usels/web";

function Component() {
  const input$ = useObservable("");

  useObserveDebounced(
    () => input$.get(),
    (value) => {
      console.log("submit:", value);
    },
    { ms: 300, maxWait: 1000 }
  );
}

Scope

import { observable, observeDebounced } from "@usels/web";

function Component() {
  "use scope"
  const input$ = observable("");

  observeDebounced(
    () => input$.get(),
    (value) => {
      console.log("submit:", value);
    },
    { ms: 300, maxWait: 1000 }
  );
}

Eager mode (immediate: true)

Pass immediate: true to execute the effect immediately on setup, in addition to triggering on source changes.

Hook

import { useObservable, useObserveDebounced } from "@usels/web";

function Component() {
  const count$ = useObservable(0);

  // ✅ Also executes the effect immediately with the initial value
  useObserveDebounced(
    () => count$.get(),
    (value) => {
      console.log("value:", value);
    },
    { ms: 300, immediate: true }
  );
}

Scope

import { observable, observeDebounced } from "@usels/web";

function Component() {
  "use scope"
  const count$ = observable(0);

  // ✅ Also executes the effect immediately with the initial value
  observeDebounced(
    () => count$.get(),
    (value) => {
      console.log("value:", value);
    },
    { ms: 300, immediate: true }
  );
}

Batch scheduling (schedule)

The schedule option controls when the effect runs relative to Legend-State’s batch cycle.

• schedule: 'sync' — runs synchronously inside the batch (equivalent to Legend-State immediate: true)
• schedule: 'deferred' — runs after the batch ends (equivalent to Legend-State immediate: false)
• omitted — uses Legend-State’s default batching

useObserveDebounced(count$, (v) => console.log(v), { ms: 300, schedule: "sync" });

Type

export { observeDebounced, type ObserveDebouncedOptions } from "./core";
export type UseObserveDebounced = typeof observeDebounced;
/**
 * Runs a reactive effect debounced — fires only after `ms` milliseconds of inactivity.
 *
 * Built on `watch` — lazy by default (`immediate: false`).
 * The selector always tracks deps; only the effect is debounced.
 *
 * @param selector - Observable, array of Observables, or reactive read function.
 * @param effect   - Side-effect callback. Fires after debounce delay.
 * @param options  - `ms` (default 200), `maxWait`, `immediate`, `schedule`.
 *
 * @example
 * ```tsx twoslash
 * // @noErrors
 * import { useObserveDebounced } from "@usels/core";
 * import { observable } from "@legendapp/state";
 *
 * const query$ = observable("");
 *
 * useObserveDebounced(
 *   () => query$.get(),
 *   (value) => { console.log("search:", value); },
 *   { ms: 300 }
 * );
 * ```
 */
export declare const useObserveDebounced: UseObserveDebounced;

Source

View on GitHub