Skip to main content

useRateLimitedCallback

Returns a stable function that runs a callback at most limit times per windowMs, using a token bucket. Calls beyond the limit are dropped or queued, and the function tells you which happened.

It differs from the other timing hooks: debouncing (useDebouncedCallback) waits for a quiet period, and throttling (useThrottledValue) spaces updates evenly. A rate limiter allows a burst up to the limit, then enforces the average rate.

When to use it​

  • Staying under an API's quota, such as 5 requests per 10 seconds.
  • Sending analytics or telemetry events in order without flooding the server (overflow: "queue").
  • Protecting an expensive action, such as exports or searches, from being triggered too often, and telling the user when it happens (onLimited).
  • Limiting how often a handler fires from a noisy source (socket messages, pointer events) while still allowing short bursts.

Demo​

Click Send request quickly to use up the 3 tokens, then watch one return every 2 seconds. The second example queues events and delivers them in order, and the last one shows a hint when searches are skipped. Open the Console tab to see what ran and what was dropped.

Loading demo…

Signature​

interface UseRateLimitedCallbackOptions<A extends unknown[] = unknown[]> {
limit: number;
windowMs: number;
overflow?: "drop" | "queue";
maxQueue?: number;
onLimited?: (...args: A) => void;
}

interface RateLimitedFunction<A extends unknown[]> {
(...args: A): boolean;
cancel: () => void;
remaining: () => number;
pending: () => number;
}

function useRateLimitedCallback<A extends unknown[]>(
callback: (...args: A) => void,
options: UseRateLimitedCallbackOptions<A>
): RateLimitedFunction<A>;
ParameterTypeDescription
callback(...args: A) => voidThe function to limit.
optionsUseRateLimitedCallbackOptionsThe limit, window and overflow.
OptionTypeDescription
limitnumberThe most calls that may run within windowMs, and the size of a burst. Rounded down.
windowMsnumberThe window, in milliseconds, over which limit calls are allowed. 0 or less means no limit.
overflow"drop" | "queue"What to do with a call when no token is left. Defaults to "drop".
maxQueuenumberThe most calls kept waiting when overflow is "queue". Further calls are dropped. Defaults to Infinity.
onLimited(...args: A) => voidCalled with the arguments of every dropped call.

Returns: a function with the same parameters as callback that returns true when the call ran or was queued, and false when it was dropped. It also has these members:

MemberDescription
cancel()Discards every queued call. Tokens already spent are not refunded.
remaining()The whole number of calls that would run right now.
pending()The number of calls waiting in the queue.

Usage notes​

  • How the bucket works. It starts full with limit tokens. Each call spends one, and tokens come back smoothly at limit / windowMs per millisecond, never above limit. With limit: 3, windowMs: 6000, three calls run at once and then one more every 2 seconds, rather than all three returning after 6 seconds.
  • Drop or queue. With "drop" an excess call is discarded and onLimited receives its arguments. With "queue" it waits and runs, in order, as tokens refill. Calls never jump the queue: while any call is waiting, new calls wait behind it. When the queue holds maxQueue calls, further calls are dropped and reported to onLimited. Set maxQueue when calls can arrive faster than the limit for a long time, as the default queue is unbounded.
  • Return value. true means the callback ran or was accepted into the queue; false means it was dropped. The callback's own return value is ignored.
  • remaining and pending are not reactive. They read the current state and do not re-render your component. Use them in handlers, or poll them (for example with useInterval) to show a meter, as the demo does.
  • Stable identity, latest values. The returned function (and its members) never changes between renders. It always runs the latest callback, including for queued calls, and reads the latest options. A new limit or windowMs applies from the next call or refill and does not reset spent tokens; a lower limit caps the bucket straight away. The callback is read after each commit, so call the function from handlers and effects rather than during render.
  • Unmount. The queue and timer are cleared, and calls made afterwards are ignored (they return false, and onLimited is not called). Nothing runs after unmount.
  • Errors. If the callback throws, the error reaches the caller. For a queued call it is thrown from the timer, and later queued calls still run.
  • Edge cases. A limit below 1 (or NaN) means no call ever runs, even when queueing. A windowMs of 0, negative or NaN disables the limit. A limit of Infinity never limits. An infinite windowMs never refills.
  • Per instance. Each hook instance has its own bucket. The limit is not shared between components, tabs or page loads. To share one quota, lift the hook up, or enforce it on the server as well.
  • Safe under React StrictMode.

Example​

const search = useRateLimitedCallback((query: string) => fetchResults(query), {
limit: 5,
windowMs: 10_000,
onLimited: () => toast("Slow down a little"),
});

return <input onChange={(e) => search(e.target.value)} />;
// Send events in order, at most 2 per second, holding up to 50 back
const track = useRateLimitedCallback(sendEvent, {
limit: 2,
windowMs: 1000,
overflow: "queue",
maxQueue: 50,
});

// Drop what is still waiting, for example when the user signs out
const onSignOut = () => track.cancel();

Hook source​

View useRateLimitedCallback source

use-rate-limited-callback.ts
import { useEffect, useState } from "react";

import { useLatest } from "./use-latest";

/** The longest delay `setTimeout` supports, in milliseconds. Larger values fire immediately. */
const MAX_TIMEOUT_MS = 2 ** 31 - 1;
/** Absorbs floating point error, so a token that is 0.9999999 full counts as a whole one. */
const EPSILON = 1e-9;

/** Options for {@link useRateLimitedCallback}. */
export interface UseRateLimitedCallbackOptions<
A extends unknown[] = unknown[],
> {
/**
* The most calls that may run within `windowMs`, and the size of a burst. It
* is rounded down; a value below `1` means no call ever runs.
*/
limit: number;
/**
* The window, in milliseconds, over which `limit` calls are allowed. Tokens
* refill smoothly at `limit / windowMs` per millisecond. `0` or less means no
* limit.
*/
windowMs: number;
/**
* What to do with a call that arrives when no token is left: `"drop"`
* discards it, `"queue"` runs it, in order, as tokens refill. Default is
* `"drop"`.
*/
overflow?: "drop" | "queue";
/**
* The most calls kept waiting when `overflow` is `"queue"`. A call that
* finds the queue full is dropped. Default is `Infinity`.
*/
maxQueue?: number;
/**
* Called synchronously with the arguments of every call that is dropped:
* none left in `"drop"` mode, or a full queue in `"queue"` mode. Not called
* when a queued call is discarded by `cancel` or on unmount.
*/
onLimited?: (...args: A) => void;
}

/**
* A rate-limited function returned by {@link useRateLimitedCallback}, with
* controls to inspect and clear the limiter.
*
* @typeParam A - The argument list of the limited callback.
*/
export interface RateLimitedFunction<A extends unknown[]> {
/**
* Calls the callback if a token is left, otherwise drops or queues the call.
*
* @returns `true` if the call ran now or was added to the queue, `false` if
* it was dropped.
*/
(...args: A): boolean;
/** Discard every queued call. Tokens already spent are not refunded. */
cancel: () => void;
/** The whole number of calls that would run right now. */
remaining: () => number;
/** The number of calls waiting in the queue. */
pending: () => number;
}

/**
* Returns a stable function that runs `callback` at most `limit` times per
* `windowMs`, using a token bucket.
*
* The bucket starts full, so up to `limit` calls run immediately as a burst.
* Each call spends a token, and tokens refill smoothly at `limit / windowMs`
* per millisecond, up to `limit`. This sets it apart from
* `useDebouncedCallback` (waits for a quiet period) and `useThrottledValue`
* (one update per interval): bursts are allowed, but the average rate is not.
*
* When no token is left, the call is dropped (default) or, with
* `overflow: "queue"`, queued and run in order as tokens refill, up to
* `maxQueue`. The returned function reports whether a call ran or was queued
* (`true`) or dropped (`false`), and `onLimited` receives the dropped
* arguments. Use `remaining` and `pending` to read the limiter's state, and
* `cancel` to empty the queue. They read the current state and do not
* re-render your component.
*
* The returned function keeps the same identity for the lifetime of the
* component and always runs the latest `callback` and options, so it is safe
* in dependency arrays and long-lived listeners. A new `limit` or `windowMs`
* applies from the next call or refill, without resetting spent tokens. The
* return value of `callback` is ignored. On unmount the queue and timer are
* cleared and later calls are ignored (they return `false`), so nothing runs
* after unmount.
*
* @typeParam A - The argument list of the callback.
* @param callback - The function to limit.
* @param options - The {@link UseRateLimitedCallbackOptions | limit, window and overflow} behavior.
* @returns A {@link RateLimitedFunction | rate-limited function} with `cancel`, `remaining` and `pending`.
*
* @example
* ```tsx
* // At most 5 searches every 10 seconds, extra ones are dropped
* const search = useRateLimitedCallback(
* (query: string) => fetchResults(query),
* {
* limit: 5,
* windowMs: 10_000,
* onLimited: () => toast("Slow down a little"),
* }
* );
*
* return <input onChange={(e) => search(e.target.value)} />;
* ```
*
* @example
* ```tsx
* // Send events in order, at most 2 per second, holding up to 50 back
* const track = useRateLimitedCallback(sendEvent, {
* limit: 2,
* windowMs: 1000,
* overflow: "queue",
* maxQueue: 50,
* });
* ```
*
* For a live, editable example, see the [useRateLimitedCallback docs page](https://altalyst-solutions.github.io/hookify/hooks/use-rate-limited-callback).
*/
export const useRateLimitedCallback = <A extends unknown[]>(
callback: (...args: A) => void,
options: UseRateLimitedCallbackOptions<A>
): RateLimitedFunction<A> => {
/** Refs to the latest callback and options, so changing them never resets the limiter. */
const latest = useLatest({ callback, options });

// The limiter lives outside React state: it is created once per component and
// never causes a re-render, which keeps the returned function stable.
const [limited] = useState(() => {
/**
* The tokens in the bucket. It is fractional, because tokens refill
* continuously. `null` means the bucket was never used, so it is full at
* whatever `limit` is by then.
*/
let tokens: number | null = null;
/** When `tokens` was last brought up to date, from a monotonic clock. */
let refilledAt = performance.now();
/** The timer that runs the next queued call, if any call is waiting. */
let timer: ReturnType<typeof setTimeout> | null = null;
/** `true` once the component has unmounted, so later calls are ignored. */
let disposed = false;
/** The arguments of the calls waiting for a token, oldest first. */
const queue: A[] = [];

/** The size of the bucket: `limit`, rounded down, and `0` when invalid. */
const getCapacity = () => {
const { limit } = latest.current.options;
return Number.isNaN(limit) ? 0 : Math.max(0, Math.floor(limit));
};

/**
* Adds the tokens earned since the last refill, up to the capacity, using
* the latest options. Tokens are computed on demand from the elapsed time,
* so there is no timer ticking while nobody is calling.
*
* @returns The tokens in the bucket.
*/
const refill = () => {
const { windowMs } = latest.current.options;
const capacity = getCapacity();
const now = performance.now();
const elapsed = now - refilledAt;
refilledAt = now;

// Without a usable window there is nothing to wait for, so the bucket is
// always full.
if (tokens === null || !(windowMs > 0)) {
tokens = capacity;
} else if (elapsed > 0) {
tokens = Math.min(capacity, tokens + elapsed * (capacity / windowMs));
} else {
tokens = Math.min(capacity, tokens);
}
return tokens;
};

/** Stops the timer that would run the next queued call. */
const clearTimer = () => {
if (timer !== null) clearTimeout(timer);
timer = null;
};

/** Spends one token. Call `refill` first. */
const take = () => {
tokens = (tokens ?? 0) - 1;
};

/**
* Arms one timer for the moment the next token is due, when calls are
* waiting and none is armed. Doing it per token, rather than on a fixed
* tick, means an empty queue costs nothing.
*/
const schedule = () => {
if (timer !== null || queue.length === 0 || disposed) return;
const { windowMs } = latest.current.options;
const rate = getCapacity() / windowMs;
const wait = (1 - (tokens ?? 0)) / rate;
// Tokens never come back (a rate of 0), so there is nothing to wait for.
if (!Number.isFinite(wait)) return;
timer = setTimeout(
drain,
Math.min(Math.ceil(Math.max(wait, 0)), MAX_TIMEOUT_MS)
);
};

/**
* Runs as many queued calls as there are tokens for, then re-arms the
* timer for the rest. It re-reads the options each time, so a `limit` or
* `windowMs` that changed while waiting is respected.
*/
const drain = () => {
timer = null;
// `finally` so a throwing callback can't leave the rest of the queue
// without a timer.
try {
refill();
while (queue.length > 0 && (tokens ?? 0) >= 1 - EPSILON) {
take();
latest.current.callback(...(queue.shift() as A));
}
} finally {
schedule();
}
};

/** The rate-limited function handed to the consumer. */
const fn = ((...args: A) => {
if (disposed) return false;

const {
overflow = "drop",
maxQueue = Infinity,
onLimited,
} = latest.current.options;
const available = refill();

// Run now only if nobody is queued, so calls keep their order.
if (queue.length === 0 && available >= 1 - EPSILON) {
take();
latest.current.callback(...args);
return true;
}

// Queue instead of dropping. A bucket that can never hold a token would
// keep the call waiting forever, so it is dropped.
if (
overflow === "queue" &&
getCapacity() >= 1 &&
queue.length < maxQueue
) {
queue.push(args);
schedule();
return true;
}

onLimited?.(...args);
return false;
}) as RateLimitedFunction<A>;

fn.cancel = () => {
clearTimer();
queue.length = 0;
};
// The epsilon keeps a token that is 0.9999999 full from reading as `0`.
fn.remaining = () => Math.max(0, Math.floor(refill() + EPSILON));
fn.pending = () => queue.length;

return {
fn,
/** Allows calls again. Runs on mount and after StrictMode's simulated unmount. */
attach: () => {
disposed = false;
},
/** Ignores later calls and discards the queue, so nothing runs after unmount. */
dispose: () => {
disposed = true;
fn.cancel();
},
};
});

useEffect(() => {
limited.attach();
return limited.dispose;
}, [limited]);

return limited.fn;
};