`throttle`

Invokes a function at most once per wait period — on a schedule, unlike debounce's "wait for quiet."

Throttled<T> throttle<T>(void Function(T arg) func, Duration wait, {bool leading = true, bool trailing = true}) class Throttled<T> { void call(T arg); // Throttled is callable: throttled(arg) void cancel(); } FxEvents<T> FxEvents<T>.throttle(Duration window, {bool leading = true, bool trailing = false}) // chain (events) Throttled<T> (void Function(T arg)).fxThrottle(Duration wait, {bool leading = true, bool trailing = true}) // method

Lecture

throttle guarantees func runs at most once every wait, no matter how often the throttled function is called. That's the key difference from debounce: debounce keeps resetting its timer on every call, so a continuous stream of calls can delay execution indefinitely; throttle's window is fixed once it starts, so calls still get through on a regular cadence — useful for things like scroll or resize handlers where you want periodic updates, not just one at the very end.

Both leading and trailing default to true: the first call in a window fires immediately (leading edge), and if more calls arrive before the window closes, the last of those fires once the window ends (trailing edge, with the latest argument). Turn either off to get leading-only or trailing-only behavior. Like debounce, the returned Throttled<T> is a callable class with a .cancel() to drop a pending trailing call.

Demo 1 · Leading + trailing (the default)

The first call fires immediately; the last call in the window fires again once the window closes:

Demo 2 · Tuning leading/trailing, and cancel()

Turn off leading for trailing-only behavior, off trailing for leading-only, or call .cancel() to drop a pending trailing call:

import 'package:fxdart/fxdart.dart';

Future<void> main() async {
  // leading: false — suppress the immediate call, only the trailing edge fires.
  final trailingOnlyCalls = <String>[];
  final trailingOnly = throttle<String>(
      (s) => trailingOnlyCalls.add(s), const Duration(milliseconds: 100),
      leading: false, trailing: true);
  trailingOnly('a');
  trailingOnly('b');
  print(trailingOnlyCalls); // [] — no leading call this time
  await sleep(const Duration(milliseconds: 150));
  print(trailingOnlyCalls); // [b]

// trailing: false — only the leading edge ever fires.
  final leadingOnlyCalls = <String>[];
  final leadingOnly = throttle<String>(
      (s) => leadingOnlyCalls.add(s), const Duration(milliseconds: 100),
      leading: true, trailing: false);
  leadingOnly('x');
  leadingOnly('y');
  leadingOnly('z');
  await sleep(const Duration(milliseconds: 150));
  print(leadingOnlyCalls); // [x] — y and z are dropped, no trailing call

// .cancel() drops a pending trailing call.
  final cancelCalls = <String>[];
  final cancelThrottled = throttle<String>(
      (s) => cancelCalls.add(s), const Duration(milliseconds: 100));
  cancelThrottled('first');
  cancelThrottled('second'); // would trigger a trailing call...
  cancelThrottled.cancel(); // ...but this cancels it
  await sleep(const Duration(milliseconds: 150));
  print(cancelCalls); // [first]
}

Method spelling

Same as debounce: onScroll.fxThrottle(wait) is throttle(onScroll, wait), and it forwards leading and trailing unchanged.

void onScroll(double offset) => _measure(offset);

final handler = onScroll.fxThrottle(
  const Duration(milliseconds: 100),
  trailing: false,
);

The fx prefix names the library doing the wrapping, the same convention as the getter spellings in fx.

Try it yourself

Exercise: wrap onClick in throttle (100ms wait) so rapid clicks register at most twice — leading and trailing — instead of three separate times.

On event streams

The same idea exists on the events layer: when the chatty thing is a Stream rather than a callback, fxEvents(s).throttle(window, trailing: …) lets one event per window through. One default differs: the stream form is leading-only unless you pass trailing: true (the callback wrapper above defaults both edges on). See fxEvents for the chain this belongs to.

import 'dart:async';

import 'package:fxdart/fxdart.dart';

/// Emits each (offsetMs, value) pair at its offset, closing at [closeMs].
Stream<T> timed<T>(List<(int, T)> events, int closeMs) {
  final c = StreamController<T>();
  for (final (ms, v) in events) {
    Timer(Duration(milliseconds: ms), () => c.add(v));
  }
  Timer(Duration(milliseconds: closeMs), c.close);
  return c.stream;
}

Future<void> main() async {
  // The same idea on a Stream: scroll positions fire constantly; one
  // per 100ms window gets through. Default is leading only.
  final leading = await fxEvents(timed(
          [(0, 0), (30, 40), (60, 90), (130, 160), (160, 220), (300, 400)],
          450))
      .throttle(const Duration(milliseconds: 100))
      .toList();
  print(leading); // [0, 160, 400] — the first event of each window

// trailing: true emits the NEWEST value seen when each window ends —
  // note the stream form defaults to trailing: false, unlike the
  // callback wrapper above.
  final trailing = await fxEvents(
          timed([(0, 0), (30, 40), (60, 90), (130, 160), (300, 400)], 450))
      .throttle(const Duration(milliseconds: 100),
          leading: false, trailing: true)
      .toList();
  print(trailing); // [90, 160, 400]
}

Related: debounce — waits for quiet instead of a fixed schedule · delay & sleep — building timing demos · shuffle — seeded randomness · concurrent — rate-limiting for async pipelines