Skip to main content

useDebounced

Returns a debounced copy of a value: it follows value, but only after value has stopped changing for duration. Every change restarts the timer.

List<Result>? useSearchResults(SearchService service) {
  final query = useState('');
  // Only settles 300ms after the last keystroke.
  final debouncedQuery = useDebounced(query.value, duration: const Duration(milliseconds: 300));

  // The search fires on the debounced value, not on every keystroke.
  return useMemoizedFutureData(
    () => service.search(debouncedQuery),
    keys: [debouncedQuery],
  );
}

Signature​

T useDebounced<T>(T value, {required Duration duration});
  • value - the value to debounce. On first build the returned value equals it immediately.
  • duration - how long value must stay unchanged before the debounced value catches up.

Use cases​

  • Search-as-you-type: debounce the query so the request fires after the user pauses, not on every keystroke.
  • Rate-limiting any expensive reaction to a fast-changing value - validation, a network call, a heavy recomputation.

Caveats​

  • This debounces a value you already hold; it does not debounce a callback. Pair the debounced value with the hook that consumes it - feed it into the keys of useMemoizedFuture or useAutoComputedState, as in the example above.

  • The first value is returned without delay. The debounce applies only to subsequent changes.

See also​