Skip to main content

​
Overview

The throttle utilities limit how often a function can be called. Unlike debouncing which delays execution, throttling ensures a function is called at most once in a specified time period.

​
Import

import { 
  throttleByTimeout, 
  throttleByTime, 
  throttleByFrame 
} from "@zayne-labs/toolkit-core";

​
throttleByTimeout

Throttles function execution using setTimeout. Ensures the function is called at most once per delay period.

​
Signature

function throttleByTimeout<TCallbackFn extends AnyFunction>(
  callbackFn: TCallbackFn,
  delay: number
): ThrottledByTimeoutFn<TCallbackFn>

​
Parameters

​
callbackFn
TCallbackFn
required
The function to throttle.
​
delay
number
required
The number of milliseconds to throttle invocations to.

​
Return Value

​
ThrottledByTimeoutFn<TCallbackFn>
function
A throttled function with the following members:
​
(...parameters)
void
Call the throttled function. Will only execute if no call is pending.
​
cancelTimeout
() => void
Cancels any pending timeout.

​
Example

const handleResize = () => {
  console.log("Window resized:", window.innerWidth);
};

const throttledResize = throttleByTimeout(handleResize, 200);

window.addEventListener("resize", throttledResize);

// Cleanup
window.removeEventListener("resize", throttledResize);
throttledResize.cancelTimeout();

​
throttleByTime

Throttles function execution based on elapsed time since the last invocation. Uses Date.now() for time tracking.

​
Signature

function throttleByTime<TCallbackFn extends AnyFunction>(
  callbackFn: TCallbackFn,
  delay: number
): ThrottledByTimeFn<TCallbackFn>

​
Parameters

​
callbackFn
TCallbackFn
required
The function to throttle.
​
delay
number
required
The minimum time in milliseconds between function invocations.

​
Return Value

​
ThrottledByTimeFn<TCallbackFn>
function
A throttled function that accepts the same parameters as the original callback.

​
Example

const trackScrollPosition = (event: Event) => {
  console.log("Scroll Y:", window.scrollY);
};

const throttledScroll = throttleByTime(trackScrollPosition, 100);

window.addEventListener("scroll", throttledScroll);

​
throttleByFrame

Throttles function execution to run at most once per animation frame using requestAnimationFrame.

​
Signature

function throttleByFrame<TCallbackFn extends AnyFunction>(
  callbackFn: TCallbackFn
): ThrottledByFrameFn<TCallbackFn>

​
Parameters

​
callbackFn
TCallbackFn
required
The function to throttle to animation frames.

​
Return Value

​
ThrottledByFrameFn<TCallbackFn>
function
A throttled function with the following members:
​
(...parameters)
void
Call the throttled function. Will only execute once per animation frame.
​
cancelAnimation
() => void
Cancels any pending animation frame request.

​
Example

const updateParallax = () => {
  const scrollY = window.scrollY;
  document.querySelector(".parallax")?.style.setProperty(
    "transform",
    `translateY(${scrollY * 0.5}px)`
  );
};

const throttledParallax = throttleByFrame(updateParallax);

window.addEventListener("scroll", throttledParallax);

// Cleanup
window.removeEventListener("scroll", throttledParallax);
throttledParallax.cancelAnimation();

​
Comparison

StrategyBest ForCancellableTiming Mechanism
throttleByTimeoutNetwork requests, API callsYessetTimeout
throttleByTimeHigh-frequency events, loggingNoDate.now()
throttleByFrameVisual updates, animationsYesrequestAnimationFrame

​
Common Use Cases

​
throttleByTimeout

  • API rate limiting
  • Button click protection
  • Form submission throttling

​
throttleByTime

  • Scroll event handlers
  • Mouse move tracking
  • Keyboard input logging

​
throttleByFrame

  • Scroll-based animations
  • Drag and drop operations
  • Canvas rendering
  • Parallax effects

​
Notes

  • throttleByTimeout: Executes after the delay period, suitable for async operations
  • throttleByTime: Executes immediately if enough time has passed, best for real-time tracking
  • throttleByFrame: Syncs with browser repaint cycle (~60fps), optimal for smooth animations
  • All throttle functions preserve the original function’s parameters and type safety

Build docs developers (and LLMs) love

Get started for freeTalk to us