For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /reference/function/throttle.md.
Install massaman

    throttle es-toolkit

    Limits a function to be executed at most once per specified time interval.

    const throttledFunc = throttle(func, throttleMs, options);

    Usage

    throttle(func, throttleMs, options?)

    Use throttle when you want to limit function calls to a specific time interval. This is useful for optimizing performance when handling frequently occurring events like scrolling, resizing, or mouse movement.

    Unlike debounce, throttle ensures the function is executed at least once during the specified time period.

    import { throttle } from 'es-toolkit/function';

// Basic usage (execute at most once per second)
const throttledLog = throttle(() => {
  console.log('Function executed!');
}, 1000);

// First call: executes immediately
throttledLog(); // Logs 'Function executed!'

// Additional calls within 1 second: ignored
throttledLog();
throttledLog();

// After 1 second, the last call executes as trailing

// Scroll event optimization
const handleScroll = throttle(() => {
  console.log('Scroll position:', window.scrollY);
}, 100); // At most once per 100ms

window.addEventListener('scroll', handleScroll);

// API call optimization
const searchThrottled = throttle(async (query: string) => {
  const results = await fetch(`/api/search?q=${query}`);
  console.log('Search results:', await results.json());
}, 300);

// Even if called on every input, actual search executes only every 300ms
searchThrottled('hello');
searchThrottled('hello w');
searchThrottled('hello world');

    You can adjust the leading and trailing options.

    import { throttle } from 'es-toolkit/function';

// Enable only leading (execute only at start)
const leadingOnly = throttle(() => console.log('Leading only'), 1000, { edges: ['leading'] });

// Enable only trailing (execute only at end)
const trailingOnly = throttle(() => console.log('Trailing only'), 1000, { edges: ['trailing'] });

leadingOnly(); // Executes immediately
leadingOnly(); // Ignored
leadingOnly(); // Ignored

trailingOnly(); // Does not execute immediately
trailingOnly(); // Ignored
trailingOnly(); // Executes after 1 second

    You can also control it manually.

    import { throttle } from 'es-toolkit/function';

const throttledFunc = throttle(() => console.log('executed'), 1000);

throttledFunc(); // Executes immediately
throttledFunc(); // Waiting

// Immediately process pending execution
throttledFunc.flush();

// Cancel pending execution
throttledFunc.cancel();

    Parameters

    funcFrequired

    The function to throttle.

    throttleMsnumberrequired

    The time interval (in milliseconds) to throttle execution.

    optionsThrottleOptionsoptional

    Additional options.

    • signal (AbortSignal, optional): A signal that can cancel function execution.
    • edges (Array<'leading' | 'trailing'>, optional): Determines when to execute the function. Defaults to ['leading', 'trailing'].

    Returns

    Returns a new throttled function with cancel and flush methods.

    ThrottledFunction<F>
    Source: es-toolkit

    Re-exported verbatim from es-toolkit. Implementation, edge cases, and performance behavior are owned upstream. This page mirrors the documentation at the pinned version; the linked source is authoritative.