Framework
Version
Debouncer API Reference
Throttler API Reference
Rate Limiter API Reference
Queue API Reference

useAsyncThrottler

Function: useAsyncThrottler()

ts
function useAsyncThrottler<TFn, TArgs>(fn, options): object
function useAsyncThrottler<TFn, TArgs>(fn, options): object

Defined in: react-pacer/src/async-throttler/useAsyncThrottler.ts:42

A low-level React hook that creates an AsyncThrottler instance to limit how often an async function can execute.

This hook is designed to be flexible and state-management agnostic - it simply returns a throttler instance that you can integrate with any state management solution (useState, Redux, Zustand, Jotai, etc).

Async throttling ensures an async function executes at most once within a specified time window, regardless of how many times it is called. This is useful for rate-limiting expensive API calls, database operations, or other async tasks.

Type Parameters

TFn extends (...args) => any

TArgs extends any[]

Parameters

fn

TFn

options

AsyncThrottlerOptions

Returns

object

cancel()

ts
readonly cancel: () => void;
readonly cancel: () => void;

Cancels any pending execution

Returns

void

getExecutionCount()

ts
readonly getExecutionCount: () => number;
readonly getExecutionCount: () => number;

Returns the number of times the function has been executed

Returns

number

getNextExecutionTime()

ts
readonly getNextExecutionTime: () => number;
readonly getNextExecutionTime: () => number;

Returns the next execution time

Returns

number

maybeExecute()

ts
readonly maybeExecute: (...args) => Promise<void>;
readonly maybeExecute: (...args) => Promise<void>;

Attempts to execute the throttled function If a call is already in progress, it may be blocked or queued depending on the wait option

Parameters

args

...TArgs

Returns

Promise<void>

Example

tsx
// Basic API call throttling
const { maybeExecute } = useAsyncThrottler(
  async (id: string) => {
    const data = await api.fetchData(id);
    return data;
  },
  { wait: 1000 }
);

// With state management
const [data, setData] = useState(null);
const { maybeExecute } = useAsyncThrottler(
  async (query) => {
    const result = await searchAPI(query);
    setData(result);
  },
  {
    wait: 2000,
    leading: true,   // Execute immediately on first call
    trailing: false  // Skip trailing edge updates
  }
);
// Basic API call throttling
const { maybeExecute } = useAsyncThrottler(
  async (id: string) => {
    const data = await api.fetchData(id);
    return data;
  },
  { wait: 1000 }
);

// With state management
const [data, setData] = useState(null);
const { maybeExecute } = useAsyncThrottler(
  async (query) => {
    const result = await searchAPI(query);
    setData(result);
  },
  {
    wait: 2000,
    leading: true,   // Execute immediately on first call
    trailing: false  // Skip trailing edge updates
  }
);
Subscribe to Bytes

Your weekly dose of JavaScript news. Delivered every Monday to over 100,000 devs, for free.

Bytes

No spam. Unsubscribe at any time.